From fd16c1669de682769687aca1643d8983f3376d8b Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 20 Jul 2026 12:11:08 -0700
Subject: [PATCH 1/3] feat: add stable lease identities

---
 AGENTS.md                   |   4 +-
 README.md                   |  28 ++++-
 cmd/e2e_test.go             | 210 +++++++++++++++++++++++++++++++++++-
 cmd/get.go                  |  16 ++-
 cmd/return_cmd.go           |  72 ++++++++++---
 cmd/status.go               |  50 +++++++++
 internal/pool/pool.go       | 143 ++++++++++++++++++------
 internal/pool/pool_test.go  | 109 ++++++++++++++++++-
 internal/pool/state.go      |  13 +++
 internal/pool/state_test.go |  29 +++++
 10 files changed, 613 insertions(+), 61 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b90f483..899190a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,9 +37,9 @@ 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`, classified `DestroyLeased` by destroy (removable only when the exact path is named with `--include-leased`, NEVER via `--all`), surfaced by `status` as `StatusLeased`, and cleared by `Release` (`return`)
+- Durable leases are a separate, process-independent reservation: `WorktreeEntry.Leased`/`LeaseID`/`LeaseHolder`/`LeasedAt` persist in the state file with `omitempty`. Every acquisition generates a new immutable 128-bit random `LeaseID`; older state without it loads with an empty ID and remains releasable through the legacy unconditional path. A lease is NOT derived from live processes, so it survives with zero processes inside the worktree and `healState` never clears it. Leased worktrees are skipped by `Acquire` and `prune`, classified `DestroyLeased` by destroy (removable only when the exact path is named with `--include-leased`, NEVER via `--all`), surfaced by `status` as `StatusLeased`, and cleared by `Release` (`return`)
 - `destroy` is safe-by-default and mirrors `prune`: dry-run unless `--yes`, narrow explicit targets (`destroy <path>` for one worktree; `destroy <pool> --all` for that pool only - there is NO cross-pool/global destroy, and `--all` with no pool target is an error). The old blunt `--force` flag is REMOVED (this was the v2.0.0 breaking change); each risk class is its own opt-in: `--include-unlanded` (dirty, unmerged, or unverified), `--include-in-use` (running process or owner reservation; processes terminated cleanly first), `--include-leased` (leased, single named path only). A bare `--all --yes` removes only the disposable set (merged, clean, idle, unleased) and skips the rest with the flag that would include each. Bulk skips exit 0; a single-target skip exits non-zero. Entry points: `pool.DestroyWorktree` (single path, `allowLeased=true`) and `pool.DestroyPool` (bulk, `allowLeased=false`). Both share `classifyForDestroy` in `internal/pool/destroy.go`, which reuses prune's classification primitives (`ownerAlive`, `process.FindProcessesInWorktree`, `backingRepositoryMissing`, `git.IsDirty`, `git.IsHeadMergedIntoRef` against the `resolvePruneDefaultRef` ref) so destroy and prune agree on leased/in-use/unlanded/unverified/disposable. Removal keeps the same two-phase reservation as prune (reserve under flock, run `pre_destroy` hooks, remove only worktrees whose `sameDestroyReservation` still holds), so a worktree re-acquired during its hook is never deleted
-- `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
+- `get --lease` (see `getLeaseRunE`) is the non-interactive acquire: it opens no subshell, routes hook output and banners to stderr, and keeps path-only stdout unchanged. `get --lease --json` returns `pool.AcquireLeaseInfo`, and `status --json` exposes the same `lease_id`, holder, and timestamp. Conditional return uses `pool.ReleaseConditional` with `--if-lease-id` and optional `--if-lease-holder`; comparison, caller-side preparation, reset, and final clear share one `WithStateLock`, while return without conditions keeps the legacy path-only behavior
 - 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 732e791..1f74a24 100644
--- a/README.md
+++ b/README.md
@@ -133,7 +133,7 @@ The default treehouse root is `~/.treehouse/`.
 - **No daemon** - all operations are inline CLI commands.
   Pool state is a small on-disk file, written under a lock by each command.
 - **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.
+- **Durable leases** - `treehouse get --lease` reserves a worktree as a persistent home without keeping a process inside it. Each acquisition gets an immutable random lease identity, and the lease is recorded in treehouse's own state. 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.
 - **State recovery** - treehouse writes pool state atomically via a temp file and replacement.
   If an existing state file is empty or truncated, treehouse warns, rebuilds entries from worktrees still on disk, and marks those entries leased until you verify them with `treehouse status`.
 - **Dirty detection** - treehouse treats tracked changes and untracked files as dirty, even when repository config hides untracked files from normal `git status` output.
@@ -165,8 +165,12 @@ The default treehouse root is `~/.treehouse/`.
 | --------- | --------- | --------------------------------- |
 | `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`) |
+| `get`     | `--json` | Print `path`, `lease_id`, `lease_holder`, and `leased_at` as JSON (requires `--lease`) |
 | `enter`   | `--print-path` | Print only the worktree's absolute path to stdout instead of opening a subshell (for `cd "$(treehouse enter --print-path 1)"`) |
+| `status`  | `--json` | Print worktree status and lease metadata as JSON |
 | `return`  | `--force` | Clean, reset, and return without prompting |
+| `return`  | `--if-lease-id` | Return only if the current lease has the expected per-acquisition identity |
+| `return`  | `--if-lease-holder` | Return only if the current lease has the expected holder |
 | `prune`   | `--yes`   | Delete listed prune candidates instead of doing a dry run |
 | `prune`   | `--all`   | Sweep every managed pool under the user-level treehouse root |
 | `prune`   | `--global` | Alias for `--all` |
@@ -197,9 +201,31 @@ A bulk `treehouse destroy <pool> --all` never removes it either; only naming its
 
 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.
 
+Every acquisition receives a new random `lease_id`, including reacquiring the same path with the same holder. Automation can request a stable machine-readable allocation:
+
+```sh
+treehouse get --lease --lease-holder automation-A --json
+# {"path":"...","lease_id":"...","lease_holder":"automation-A","leased_at":"..."}
+```
+
+`treehouse status --json` returns an array with `name`, `path`, `status`, `lease_id`, `lease_holder`, `leased_at`, and `processes`. Non-leased entries use empty lease strings and a `null` timestamp. State files written before lease identities remain readable; their existing leases have an empty `lease_id` until released and acquired again.
+
 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.
 
+For retry-safe automation, condition the return on the identity from allocation or status:
+
+```sh
+treehouse return --force \
+  --if-lease-id "$lease_id" \
+  --if-lease-holder "$lease_holder" \
+  "$path"
+```
+
+Treehouse compares supplied conditions while holding the pool state lock. A missing lease or mismatch exits nonzero before process termination, worktree reset, or state clearing. The same lock fences a matching return through the final clear, so the identity succeeds once and cannot release a later acquisition of the same path. `--if-lease-holder` is optional; use `--if-lease-id` for ABA protection when a holder may be reused.
+
+For backward compatibility, `treehouse return <path>` without either condition keeps its original unconditional path-only behavior. Existing path-only scripts and `treehouse get --lease` stdout are unchanged.
+
 ### Recovering a damaged pool state file
 
 Treehouse writes `treehouse-state.json` atomically, so a crash mid-write should leave the previous state file intact.
diff --git a/cmd/e2e_test.go b/cmd/e2e_test.go
index 05c8176..16ae44b 100644
--- a/cmd/e2e_test.go
+++ b/cmd/e2e_test.go
@@ -2,14 +2,34 @@ package cmd
 
 import (
 	"bytes"
+	"encoding/hex"
+	"encoding/json"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
+	"time"
 )
 
+type leaseJSONResult struct {
+	Path        string    `json:"path"`
+	LeaseID     string    `json:"lease_id"`
+	LeaseHolder string    `json:"lease_holder"`
+	LeasedAt    time.Time `json:"leased_at"`
+}
+
+type statusJSONResult struct {
+	Name        string          `json:"name"`
+	Path        string          `json:"path"`
+	Status      string          `json:"status"`
+	LeaseID     string          `json:"lease_id"`
+	LeaseHolder string          `json:"lease_holder"`
+	LeasedAt    *time.Time      `json:"leased_at"`
+	Processes   json.RawMessage `json:"processes"`
+}
+
 var (
 	treehouseBin      string
 	exitShellBin      string
@@ -395,6 +415,14 @@ func TestStatusEmptyPool(t *testing.T) {
 	if strings.Contains(stdout, "available") || strings.Contains(stdout, "in-use") {
 		t.Errorf("expected empty status, got stdout: %s", stdout)
 	}
+
+	stdout, stderr, code = runTreehouse(t, repoDir, homeDir, nil, "status", "--json")
+	if code != 0 {
+		t.Fatalf("treehouse status --json failed (code %d): %s", code, stderr)
+	}
+	if stdout != "[]\n" {
+		t.Fatalf("empty status --json = %q, want []", stdout)
+	}
 }
 
 func TestGetAndStatus(t *testing.T) {
@@ -491,6 +519,66 @@ func TestGetLeaseRecordsHolder(t *testing.T) {
 	}
 }
 
+func TestGetLeaseAndStatusJSONContracts(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	leaseOut, leaseErr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease", "--lease-holder", "automation-A", "--json")
+	if code != 0 {
+		t.Fatalf("treehouse get --lease --json failed (code %d): %s", code, leaseErr)
+	}
+	var lease leaseJSONResult
+	if err := json.Unmarshal([]byte(leaseOut), &lease); err != nil {
+		t.Fatalf("get --lease --json returned invalid JSON %q: %v", leaseOut, err)
+	}
+	if !filepath.IsAbs(lease.Path) {
+		t.Fatalf("expected absolute lease path, got %q", lease.Path)
+	}
+	if lease.LeaseHolder != "automation-A" {
+		t.Fatalf("lease_holder = %q, want automation-A", lease.LeaseHolder)
+	}
+	decodedID, err := hex.DecodeString(lease.LeaseID)
+	if err != nil || len(decodedID) != 16 {
+		t.Fatalf("lease_id = %q, want 128-bit hexadecimal identity", lease.LeaseID)
+	}
+	if lease.LeasedAt.IsZero() {
+		t.Fatal("leased_at must be populated")
+	}
+
+	statusOut, statusErr, code := runTreehouse(t, repoDir, homeDir, nil, "status", "--json")
+	if code != 0 {
+		t.Fatalf("treehouse status --json failed (code %d): %s", code, statusErr)
+	}
+	var statuses []statusJSONResult
+	if err := json.Unmarshal([]byte(statusOut), &statuses); err != nil {
+		t.Fatalf("status --json returned invalid JSON %q: %v", statusOut, err)
+	}
+	if len(statuses) != 1 {
+		t.Fatalf("status --json returned %d worktrees, want 1: %s", len(statuses), statusOut)
+	}
+	status := statuses[0]
+	if status.Path != lease.Path || status.Status != "leased" || status.LeaseID != lease.LeaseID || status.LeaseHolder != lease.LeaseHolder {
+		t.Fatalf("status lease metadata = %#v, want allocation %#v", status, lease)
+	}
+	if status.LeasedAt == nil || !status.LeasedAt.Equal(lease.LeasedAt) {
+		t.Fatalf("status leased_at = %v, want %v", status.LeasedAt, lease.LeasedAt)
+	}
+	if string(status.Processes) != "[]" {
+		t.Fatalf("status processes = %s, want []", status.Processes)
+	}
+}
+
+func TestGetJSONRequiresLease(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+
+	stdout, stderr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--json")
+	if code == 0 {
+		t.Fatalf("get --json without --lease succeeded: stdout=%q stderr=%q", stdout, stderr)
+	}
+	if !strings.Contains(stderr, "--json requires --lease") {
+		t.Fatalf("expected actionable --json error, got %q", stderr)
+	}
+}
+
 func TestLeasedWorktreeSkippedByGetAndPrune(t *testing.T) {
 	repoDir, homeDir := setupTestRepo(t)
 
@@ -531,10 +619,10 @@ func TestLeasedWorktreeSkippedByGetAndPrune(t *testing.T) {
 	}
 }
 
-func TestReturnReleasesLease(t *testing.T) {
+func TestReturnLegacyPathOnlyIgnoresStaleCallerHolder(t *testing.T) {
 	repoDir, homeDir := setupTestRepo(t)
 
-	leaseOut, leaseErr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease")
+	leaseOut, leaseErr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease", "--lease-holder", "holder-A")
 	if code != 0 {
 		t.Fatalf("get --lease failed (code %d): %s", code, leaseErr)
 	}
@@ -543,7 +631,7 @@ func TestReturnReleasesLease(t *testing.T) {
 		t.Fatal("could not capture leased worktree path")
 	}
 
-	_, returnErr, code := runTreehouse(t, repoDir, homeDir, nil, "return", leasedPath)
+	_, returnErr, code := runTreehouse(t, repoDir, homeDir, []string{"TREEHOUSE_LEASE_HOLDER=wrong-stale-caller"}, "return", leasedPath)
 	if code != 0 {
 		t.Fatalf("return failed (code %d): %s", code, returnErr)
 	}
@@ -575,6 +663,122 @@ func TestReturnReleasesLease(t *testing.T) {
 	}
 }
 
+func TestReturnConditionalLeaseIdentityLifecycle(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+	lease := acquireLeaseJSON(t, repoDir, homeDir, "holder-A")
+	poolDir := filepath.Dir(filepath.Dir(lease.Path))
+	statePath := filepath.Join(poolDir, "treehouse-state.json")
+
+	sentinel := filepath.Join(lease.Path, "must-survive-refusal.txt")
+	if err := os.WriteFile(sentinel, []byte("preserve\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	stateBefore, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	_, stderr, code := runTreehouse(t, repoDir, homeDir, nil, "return", "--force",
+		"--if-lease-id", lease.LeaseID, "--if-lease-holder", "wrong-holder", lease.Path)
+	if code == 0 || !strings.Contains(stderr, "lease holder does not match") {
+		t.Fatalf("wrong holder should refuse, code=%d stderr=%q", code, stderr)
+	}
+	assertReturnRefusalDidNotMutate(t, statePath, stateBefore, sentinel)
+
+	wrongID := strings.Repeat("0", len(lease.LeaseID))
+	if wrongID == lease.LeaseID {
+		wrongID = strings.Repeat("1", len(lease.LeaseID))
+	}
+	_, stderr, code = runTreehouse(t, repoDir, homeDir, nil, "return", "--force",
+		"--if-lease-id", wrongID, "--if-lease-holder", lease.LeaseHolder, lease.Path)
+	if code == 0 || !strings.Contains(stderr, "lease identity does not match") {
+		t.Fatalf("wrong identity should refuse, code=%d stderr=%q", code, stderr)
+	}
+	assertReturnRefusalDidNotMutate(t, statePath, stateBefore, sentinel)
+
+	_, stderr, code = runTreehouse(t, repoDir, homeDir, nil, "return", "--force",
+		"--if-lease-id", lease.LeaseID, "--if-lease-holder", lease.LeaseHolder, lease.Path)
+	if code != 0 || !strings.Contains(stderr, "Worktree returned to pool") {
+		t.Fatalf("correct conditional return failed, code=%d stderr=%q", code, stderr)
+	}
+	if _, err := os.Stat(sentinel); !os.IsNotExist(err) {
+		t.Fatalf("correct return did not reset worktree, stat error: %v", err)
+	}
+
+	stateAfterRelease, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, stderr, code = runTreehouse(t, repoDir, homeDir, nil, "return", "--force", "--if-lease-id", lease.LeaseID, lease.Path)
+	if code == 0 || !strings.Contains(stderr, "is not leased") {
+		t.Fatalf("repeated release should refuse, code=%d stderr=%q", code, stderr)
+	}
+	stateAfterRepeat, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(stateAfterRepeat, stateAfterRelease) {
+		t.Fatalf("repeated release mutated state:\nbefore: %s\nafter: %s", stateAfterRelease, stateAfterRepeat)
+	}
+
+	current := acquireLeaseJSON(t, repoDir, homeDir, "holder-A")
+	if current.Path != lease.Path {
+		t.Fatalf("expected same worktree path after reacquisition, got %s then %s", lease.Path, current.Path)
+	}
+	if current.LeaseID == lease.LeaseID {
+		t.Fatalf("same-holder reacquisition reused lease identity %q", current.LeaseID)
+	}
+	currentState, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, stderr, code = runTreehouse(t, repoDir, homeDir, nil, "return", "--force",
+		"--if-lease-id", lease.LeaseID, "--if-lease-holder", lease.LeaseHolder, lease.Path)
+	if code == 0 || !strings.Contains(stderr, "lease identity does not match") {
+		t.Fatalf("stale same-holder identity should refuse, code=%d stderr=%q", code, stderr)
+	}
+	stateAfterStale, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(stateAfterStale, currentState) {
+		t.Fatalf("stale identity mutated current lease:\nbefore: %s\nafter: %s", currentState, stateAfterStale)
+	}
+
+	_, stderr, code = runTreehouse(t, repoDir, homeDir, nil, "return", "--force",
+		"--if-lease-id", current.LeaseID, "--if-lease-holder", current.LeaseHolder, current.Path)
+	if code != 0 {
+		t.Fatalf("current identity did not release, code=%d stderr=%q", code, stderr)
+	}
+}
+
+func acquireLeaseJSON(t *testing.T, repoDir, homeDir, holder string) leaseJSONResult {
+	t.Helper()
+	stdout, stderr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease", "--lease-holder", holder, "--json")
+	if code != 0 {
+		t.Fatalf("get --lease --json failed, code=%d stderr=%q", code, stderr)
+	}
+	var lease leaseJSONResult
+	if err := json.Unmarshal([]byte(stdout), &lease); err != nil {
+		t.Fatalf("invalid lease JSON %q: %v", stdout, err)
+	}
+	return lease
+}
+
+func assertReturnRefusalDidNotMutate(t *testing.T, statePath string, expectedState []byte, sentinel string) {
+	t.Helper()
+	stateAfter, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(stateAfter, expectedState) {
+		t.Fatalf("refused return mutated state:\nbefore: %s\nafter: %s", expectedState, stateAfter)
+	}
+	if data, err := os.ReadFile(sentinel); err != nil || string(data) != "preserve\n" {
+		t.Fatalf("refused return mutated worktree sentinel: data=%q err=%v", data, err)
+	}
+}
+
 func TestReturnExplicitPathFromOutsideRepoReleasesLease(t *testing.T) {
 	repoDir, homeDir := setupTestRepo(t)
 
diff --git a/cmd/get.go b/cmd/get.go
index c4f850c..f60d5a8 100644
--- a/cmd/get.go
+++ b/cmd/get.go
@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"encoding/json"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -20,6 +21,7 @@ import (
 var (
 	getLease       bool
 	getLeaseHolder string
+	getJSON        bool
 )
 
 var getCmd = &cobra.Command{
@@ -38,10 +40,15 @@ running inside it, until you release it with 'treehouse return <path>'.`,
 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)")
+	getCmd.Flags().BoolVar(&getJSON, "json", false, "Print lease allocation as JSON (requires --lease)")
 	rootCmd.AddCommand(getCmd)
 }
 
 func getRunE(cmd *cobra.Command, args []string) error {
+	if getJSON && !getLease {
+		return fmt.Errorf("--json requires --lease")
+	}
+
 	repoRoot, err := git.FindRepoRoot()
 	if err != nil {
 		return fmt.Errorf("not in a git repository: %w", err)
@@ -114,15 +121,18 @@ func getLeaseRunE(repoRoot, poolDir string, cfg config.Config) error {
 		holder = os.Getenv("TREEHOUSE_LEASE_HOLDER")
 	}
 
-	wtPath, err := pool.AcquireLease(repoRoot, poolDir, cfg.MaxTrees, cfg.Hooks.PostCreate, holder)
+	lease, err := pool.AcquireLeaseInfo(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))
+		ui.PrettyPath(lease.Path), ui.PrettyPath(lease.Path))
+	if getJSON {
+		return json.NewEncoder(os.Stdout).Encode(lease)
+	}
 	// The bare path is the only thing on stdout, so callers can capture it.
-	fmt.Fprintln(os.Stdout, wtPath)
+	fmt.Fprintln(os.Stdout, lease.Path)
 	return nil
 }
 
diff --git a/cmd/return_cmd.go b/cmd/return_cmd.go
index 4410310..d7bcf28 100644
--- a/cmd/return_cmd.go
+++ b/cmd/return_cmd.go
@@ -14,13 +14,25 @@ import (
 	"github.com/kunchenguid/treehouse/internal/ui"
 )
 
-var returnForce bool
-var errReturnWorktreeUnmanaged = errors.New("return worktree unmanaged")
+var (
+	returnForce         bool
+	returnIfLeaseID     string
+	returnIfLeaseHolder string
+)
+
+var (
+	errReturnWorktreeUnmanaged = errors.New("return worktree unmanaged")
+	errReturnAborted           = errors.New("return aborted")
+)
 
 var returnCmd = &cobra.Command{
 	Use:   "return [path]",
 	Short: "Terminate lingering processes and return a worktree",
 	RunE: func(cmd *cobra.Command, args []string) error {
+		if cmd.Flags().Changed("if-lease-id") && returnIfLeaseID == "" {
+			return fmt.Errorf("--if-lease-id cannot be empty")
+		}
+
 		wtPath, err := resolveWorktreePath(args)
 		if err != nil {
 			return err
@@ -34,24 +46,29 @@ var returnCmd = &cobra.Command{
 			return err
 		}
 
-		if !returnForce {
-			dirty, _ := git.IsDirty(wtPath)
-			if dirty {
-				ok, err := ui.Confirm("Worktree has uncommitted changes. Clean and return?", true)
-				if err != nil || !ok {
-					fmt.Fprintln(os.Stderr, "🌳 Aborted.")
-					return nil
-				}
+		conditional := cmd.Flags().Changed("if-lease-id") || cmd.Flags().Changed("if-lease-holder")
+		if conditional {
+			preconditions := pool.ReleasePreconditions{}
+			if cmd.Flags().Changed("if-lease-id") {
+				preconditions.ExpectedLeaseID = &returnIfLeaseID
 			}
-
-			if err := git.DetachWorktree(wtPath); err != nil {
-				return fmt.Errorf("failed to detach worktree HEAD: %w", err)
+			if cmd.Flags().Changed("if-lease-holder") {
+				preconditions.ExpectedLeaseHolder = &returnIfLeaseHolder
+			}
+			err = pool.ReleaseConditional(poolDir, wtPath, preconditions, func() error {
+				return prepareWorktreeReturn(wtPath)
+			})
+		} else {
+			err = prepareWorktreeReturn(wtPath)
+			if err == nil {
+				err = pool.Release(poolDir, wtPath)
 			}
 		}
-
-		killLingeringProcesses(wtPath)
-
-		if err := pool.Release(poolDir, wtPath); err != nil {
+		if errors.Is(err, errReturnAborted) {
+			fmt.Fprintln(os.Stderr, "🌳 Aborted.")
+			return nil
+		}
+		if err != nil {
 			return fmt.Errorf("failed to return worktree: %w", err)
 		}
 
@@ -62,9 +79,30 @@ var returnCmd = &cobra.Command{
 
 func init() {
 	returnCmd.Flags().BoolVar(&returnForce, "force", false, "Clean, reset, and return without prompting")
+	returnCmd.Flags().StringVar(&returnIfLeaseID, "if-lease-id", "", "Return only if the current lease has this identity")
+	returnCmd.Flags().StringVar(&returnIfLeaseHolder, "if-lease-holder", "", "Return only if the current lease has this holder")
 	rootCmd.AddCommand(returnCmd)
 }
 
+func prepareWorktreeReturn(wtPath string) error {
+	if !returnForce {
+		dirty, _ := git.IsDirty(wtPath)
+		if dirty {
+			ok, err := ui.Confirm("Worktree has uncommitted changes. Clean and return?", true)
+			if err != nil || !ok {
+				return errReturnAborted
+			}
+		}
+
+		if err := git.DetachWorktree(wtPath); err != nil {
+			return fmt.Errorf("failed to detach worktree HEAD: %w", err)
+		}
+	}
+
+	killLingeringProcesses(wtPath)
+	return nil
+}
+
 func resolveWorktreePath(args []string) (string, error) {
 	if len(args) > 0 {
 		return filepath.Abs(args[0])
diff --git a/cmd/status.go b/cmd/status.go
index d38f876..51e557e 100644
--- a/cmd/status.go
+++ b/cmd/status.go
@@ -1,9 +1,11 @@
 package cmd
 
 import (
+	"encoding/json"
 	"fmt"
 	"os"
 	"strings"
+	"time"
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
@@ -14,6 +16,23 @@ import (
 	"github.com/kunchenguid/treehouse/internal/ui"
 )
 
+var statusJSON bool
+
+type statusJSONProcess struct {
+	PID  int32  `json:"pid"`
+	Name string `json:"name"`
+}
+
+type statusJSONWorktree struct {
+	Name        string              `json:"name"`
+	Path        string              `json:"path"`
+	Status      string              `json:"status"`
+	LeaseID     string              `json:"lease_id"`
+	LeaseHolder string              `json:"lease_holder"`
+	LeasedAt    *time.Time          `json:"leased_at"`
+	Processes   []statusJSONProcess `json:"processes"`
+}
+
 var statusCmd = &cobra.Command{
 	Use:   "status",
 	Short: "Show the status of all worktrees in the pool",
@@ -38,6 +57,10 @@ var statusCmd = &cobra.Command{
 			return err
 		}
 
+		if statusJSON {
+			return writeStatusJSON(worktrees)
+		}
+
 		if len(worktrees) == 0 {
 			fmt.Fprintln(os.Stderr, "🌳 No worktrees in pool.")
 			return nil
@@ -88,5 +111,32 @@ var statusCmd = &cobra.Command{
 }
 
 func init() {
+	statusCmd.Flags().BoolVar(&statusJSON, "json", false, "Print pool status as JSON")
 	rootCmd.AddCommand(statusCmd)
 }
+
+func writeStatusJSON(worktrees []pool.WorktreeStatus) error {
+	output := make([]statusJSONWorktree, 0, len(worktrees))
+	for _, wt := range worktrees {
+		item := statusJSONWorktree{
+			Name:        wt.Name,
+			Path:        wt.Path,
+			Status:      wt.Status,
+			LeaseID:     wt.LeaseID,
+			LeaseHolder: wt.LeaseHolder,
+			Processes:   make([]statusJSONProcess, 0, len(wt.Processes)),
+		}
+		if !wt.LeasedAt.IsZero() {
+			leasedAt := wt.LeasedAt
+			item.LeasedAt = &leasedAt
+		}
+		for _, process := range wt.Processes {
+			item.Processes = append(item.Processes, statusJSONProcess{
+				PID:  process.PID,
+				Name: process.Name,
+			})
+		}
+		output = append(output, item)
+	}
+	return json.NewEncoder(os.Stdout).Encode(output)
+}
diff --git a/internal/pool/pool.go b/internal/pool/pool.go
index 550e00b..f6219bd 100644
--- a/internal/pool/pool.go
+++ b/internal/pool/pool.go
@@ -1,6 +1,7 @@
 package pool
 
 import (
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -27,8 +28,20 @@ type WorktreeStatus struct {
 	Path      string
 	Status    string
 	Processes []process.ProcessInfo
+	// LeaseID identifies the current acquisition of a leased worktree.
+	LeaseID string
 	// LeaseHolder is the recorded holder for a leased worktree, if any.
 	LeaseHolder string
+	// LeasedAt records when the current lease was acquired.
+	LeasedAt time.Time
+}
+
+// LeaseInfo is the stable machine-readable identity of one lease acquisition.
+type LeaseInfo struct {
+	Path        string    `json:"path"`
+	LeaseID     string    `json:"lease_id"`
+	LeaseHolder string    `json:"lease_holder"`
+	LeasedAt    time.Time `json:"leased_at"`
 }
 
 // acquireOptions controls how Acquire reserves the worktree it hands out.
@@ -48,10 +61,11 @@ type acquireOptions struct {
 // 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{
+	acquired, err := acquire(repoRoot, poolDir, poolSize, postCreate, acquireOptions{
 		hookStdout: os.Stdout,
 		hookStderr: os.Stderr,
 	})
+	return acquired.Path, err
 }
 
 // AcquireLease reserves a clean worktree and marks it durably LEASED so the
@@ -60,6 +74,13 @@ func Acquire(repoRoot, poolDir string, poolSize int, postCreate []string) (strin
 // 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) {
+	lease, err := AcquireLeaseInfo(repoRoot, poolDir, poolSize, postCreate, holder)
+	return lease.Path, err
+}
+
+// AcquireLeaseInfo reserves a worktree exactly like AcquireLease and returns
+// the immutable identity and metadata for that acquisition.
+func AcquireLeaseInfo(repoRoot, poolDir string, poolSize int, postCreate []string, holder string) (LeaseInfo, error) {
 	return acquire(repoRoot, poolDir, poolSize, postCreate, acquireOptions{
 		lease:       true,
 		leaseHolder: holder,
@@ -68,20 +89,20 @@ func AcquireLease(repoRoot, poolDir string, poolSize int, postCreate []string, h
 	})
 }
 
-func acquire(repoRoot, poolDir string, poolSize int, postCreate []string, opts acquireOptions) (string, error) {
+func acquire(repoRoot, poolDir string, poolSize int, postCreate []string, opts acquireOptions) (LeaseInfo, error) {
 	branch, err := git.GetDefaultBranch(repoRoot)
 	if err != nil {
-		return "", err
+		return LeaseInfo{}, err
 	}
 
 	fmt.Fprintf(os.Stderr, "🌳 Setting up worktree...\n")
 	if git.HasRemote(repoRoot, "origin") {
 		if err := git.Fetch(repoRoot); err != nil {
-			return "", fmt.Errorf("fetch failed: %w", err)
+			return LeaseInfo{}, fmt.Errorf("fetch failed: %w", err)
 		}
 	}
 
-	var acquired string
+	var acquired LeaseInfo
 	var runPostCreate bool
 
 	err = WithStateLock(poolDir, func() error {
@@ -112,7 +133,7 @@ func acquire(repoRoot, poolDir string, poolSize int, postCreate []string, opts a
 			if err := markAcquired(&state.Worktrees[i], opts); err != nil {
 				return err
 			}
-			acquired = wt.Path
+			acquired = leaseInfoFromEntry(state.Worktrees[i])
 			if err := WriteState(poolDir, state); err != nil {
 				return err
 			}
@@ -147,7 +168,7 @@ func acquire(repoRoot, poolDir string, poolSize int, postCreate []string, opts a
 		}
 		state.Worktrees = append(state.Worktrees, entry)
 
-		acquired = wtPath
+		acquired = leaseInfoFromEntry(entry)
 		if err := WriteState(poolDir, state); err != nil {
 			return err
 		}
@@ -155,20 +176,34 @@ func acquire(repoRoot, poolDir string, poolSize int, postCreate []string, opts a
 		return nil
 	})
 	if err != nil {
-		return "", err
+		return LeaseInfo{}, err
 	}
 	if runPostCreate {
-		hooks.Run(postCreate, acquired, opts.hookStdout, opts.hookStderr)
+		hooks.Run(postCreate, acquired.Path, opts.hookStdout, opts.hookStderr)
 	}
 
 	return acquired, nil
 }
 
+func leaseInfoFromEntry(wt WorktreeEntry) LeaseInfo {
+	return LeaseInfo{
+		Path:        wt.Path,
+		LeaseID:     wt.LeaseID,
+		LeaseHolder: wt.LeaseHolder,
+		LeasedAt:    wt.LeasedAt,
+	}
+}
+
 // 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 {
+		leaseID, err := newLeaseID()
+		if err != nil {
+			return err
+		}
 		wt.Leased = true
+		wt.LeaseID = leaseID
 		wt.LeaseHolder = opts.leaseHolder
 		wt.LeasedAt = time.Now()
 		// A lease is process-independent, so it carries no owner reservation.
@@ -179,9 +214,29 @@ func markAcquired(wt *WorktreeEntry, opts acquireOptions) error {
 	return reserveOwner(wt)
 }
 
+// ErrLeasePreconditionFailed reports that a conditional release no longer
+// identifies the worktree's current lease.
+var ErrLeasePreconditionFailed = errors.New("lease precondition failed")
+
+// ReleasePreconditions optionally constrain a release to the current lease.
+// Pointer fields distinguish an omitted condition from an expected empty value.
+type ReleasePreconditions struct {
+	ExpectedLeaseID     *string
+	ExpectedLeaseHolder *string
+}
+
 // Release resets a managed worktree, clears its short-lived owner reservation or
-// durable lease, and returns it to the available pool.
+// durable lease, and returns it to the available pool. It retains the legacy
+// unconditional behavior of releasing by path.
 func Release(poolDir, worktreePath string) error {
+	return ReleaseConditional(poolDir, worktreePath, ReleasePreconditions{}, nil)
+}
+
+// ReleaseConditional verifies any lease preconditions, runs beforeReset, resets
+// the worktree, and clears its reservation while holding one state lock. The
+// callback is invoked only after all preconditions match and runs under that
+// lock so caller-side termination or detachment cannot race a later acquisition.
+func ReleaseConditional(poolDir, worktreePath string, preconditions ReleasePreconditions, beforeReset func() error) error {
 	repoRoot, err := git.FindRepoRootFrom(worktreePath)
 	if err != nil {
 		return err
@@ -190,43 +245,62 @@ func Release(poolDir, worktreePath string) error {
 	if err != nil {
 		return err
 	}
-	if err := WithStateLock(poolDir, func() error {
-		state, err := ReadState(poolDir)
-		if err != nil {
-			return err
-		}
-		for _, wt := range state.Worktrees {
-			if wt.Path == worktreePath && wt.Destroying {
-				return fmt.Errorf("worktree %s is being destroyed", worktreePath)
-			}
-		}
-		return nil
-	}); err != nil {
-		return err
-	}
-	if err := git.ResetWorktree(worktreePath, branch); err != nil {
-		return err
-	}
 	return WithStateLock(poolDir, func() error {
 		state, err := ReadState(poolDir)
 		if err != nil {
 			return err
 		}
+
+		entryIndex := -1
 		for i := range state.Worktrees {
 			if state.Worktrees[i].Path == worktreePath {
-				if state.Worktrees[i].Destroying {
-					return fmt.Errorf("worktree %s is being destroyed", worktreePath)
-				}
-				state.Worktrees[i].OwnerPID = 0
-				state.Worktrees[i].OwnerStartedAt = 0
-				clearLease(&state.Worktrees[i])
+				entryIndex = i
 				break
 			}
 		}
+		if entryIndex < 0 {
+			return fmt.Errorf("worktree %s is not managed by treehouse", worktreePath)
+		}
+
+		wt := &state.Worktrees[entryIndex]
+		if wt.Destroying {
+			return fmt.Errorf("worktree %s is being destroyed", worktreePath)
+		}
+		if err := validateReleasePreconditions(*wt, preconditions); err != nil {
+			return err
+		}
+		if beforeReset != nil {
+			if err := beforeReset(); err != nil {
+				return err
+			}
+		}
+		if err := git.ResetWorktree(worktreePath, branch); err != nil {
+			return err
+		}
+
+		wt.OwnerPID = 0
+		wt.OwnerStartedAt = 0
+		clearLease(wt)
 		return WriteState(poolDir, state)
 	})
 }
 
+func validateReleasePreconditions(wt WorktreeEntry, preconditions ReleasePreconditions) error {
+	if preconditions.ExpectedLeaseID == nil && preconditions.ExpectedLeaseHolder == nil {
+		return nil
+	}
+	if !wt.Leased {
+		return fmt.Errorf("%w: worktree %s is not leased", ErrLeasePreconditionFailed, wt.Path)
+	}
+	if preconditions.ExpectedLeaseID != nil && wt.LeaseID != *preconditions.ExpectedLeaseID {
+		return fmt.Errorf("%w: lease identity does not match worktree %s", ErrLeasePreconditionFailed, wt.Path)
+	}
+	if preconditions.ExpectedLeaseHolder != nil && wt.LeaseHolder != *preconditions.ExpectedLeaseHolder {
+		return fmt.Errorf("%w: lease holder does not match worktree %s", ErrLeasePreconditionFailed, wt.Path)
+	}
+	return nil
+}
+
 // 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) {
@@ -260,7 +334,9 @@ func List(poolDir string) ([]WorktreeStatus, error) {
 
 			if wt.Leased {
 				ws.Status = StatusLeased
+				ws.LeaseID = wt.LeaseID
 				ws.LeaseHolder = wt.LeaseHolder
+				ws.LeasedAt = wt.LeasedAt
 			} else if ownerAlive(wt) {
 				ws.Status = StatusInUse
 			} else if len(procs) > 0 {
@@ -331,6 +407,7 @@ func reserveOwner(wt *WorktreeEntry) error {
 // clearLease removes any durable lease from a worktree entry.
 func clearLease(wt *WorktreeEntry) {
 	wt.Leased = false
+	wt.LeaseID = ""
 	wt.LeaseHolder = ""
 	wt.LeasedAt = time.Time{}
 }
diff --git a/internal/pool/pool_test.go b/internal/pool/pool_test.go
index ce789ad..f0f8246 100644
--- a/internal/pool/pool_test.go
+++ b/internal/pool/pool_test.go
@@ -1,12 +1,14 @@
 package pool
 
 import (
+	"encoding/hex"
 	"errors"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"strings"
 	"sync"
+	"sync/atomic"
 	"testing"
 	"time"
 
@@ -1732,6 +1734,10 @@ func TestAcquireLease_MarksWorktreeLeasedInState(t *testing.T) {
 	if !wt.Leased || wt.LeaseHolder != "secondmate-home" {
 		t.Fatalf("expected durable lease with holder, got %#v", wt)
 	}
+	decodedID, err := hex.DecodeString(wt.LeaseID)
+	if err != nil || len(decodedID) != 16 {
+		t.Fatalf("expected 128-bit lease identity, got %q", wt.LeaseID)
+	}
 	// 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)
@@ -1820,7 +1826,7 @@ func TestRelease_ClearsLease(t *testing.T) {
 	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() {
+	if state.Worktrees[0].Leased || state.Worktrees[0].LeaseID != "" || 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))
@@ -1828,7 +1834,7 @@ func TestRelease_ClearsLease(t *testing.T) {
 		t.Fatalf("reading state file failed: %v", err)
 	}
 	stateJSON := string(data)
-	for _, field := range []string{`"leased"`, `"lease_holder"`, `"leased_at"`} {
+	for _, field := range []string{`"leased"`, `"lease_id"`, `"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)
 		}
@@ -1844,6 +1850,39 @@ func TestRelease_ClearsLease(t *testing.T) {
 	}
 }
 
+func TestRelease_PreIdentityLeaseFailsConditionalAndAllowsLegacyReturn(t *testing.T) {
+	repoDir, poolDir := setupRepo(t)
+	lease, err := AcquireLeaseInfo(repoDir, poolDir, 4, nil, "legacy-holder")
+	if err != nil {
+		t.Fatalf("AcquireLeaseInfo failed: %v", err)
+	}
+
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	state.Worktrees[0].LeaseID = ""
+	if err := WriteState(poolDir, state); err != nil {
+		t.Fatal(err)
+	}
+
+	err = ReleaseConditional(poolDir, lease.Path, ReleasePreconditions{ExpectedLeaseID: &lease.LeaseID}, nil)
+	if !errors.Is(err, ErrLeasePreconditionFailed) {
+		t.Fatalf("conditional release of pre-identity lease = %v, want precondition failure", err)
+	}
+	state, err = ReadState(poolDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !state.Worktrees[0].Leased || state.Worktrees[0].LeaseID != "" {
+		t.Fatalf("conditional refusal mutated pre-identity lease: %#v", state.Worktrees[0])
+	}
+
+	if err := Release(poolDir, lease.Path); err != nil {
+		t.Fatalf("legacy unconditional release rejected pre-identity lease: %v", err)
+	}
+}
+
 func TestList_ShowsLeasedState(t *testing.T) {
 	repoDir, poolDir := setupRepo(t)
 
@@ -1865,6 +1904,9 @@ func TestList_ShowsLeasedState(t *testing.T) {
 	if statuses[0].LeaseHolder != "secondmate-7" {
 		t.Fatalf("expected lease holder to be reported, got %q", statuses[0].LeaseHolder)
 	}
+	if statuses[0].LeaseID == "" || statuses[0].LeasedAt.IsZero() {
+		t.Fatalf("expected lease identity and timestamp to be reported, got %#v", statuses[0])
+	}
 }
 
 func TestHealState_PreservesLease(t *testing.T) {
@@ -2026,6 +2068,69 @@ func TestAcquireLease_ConcurrentAcquiresNeverDoubleLease(t *testing.T) {
 	}
 }
 
+func TestReleaseConditional_ConcurrentIdentityReleasesExactlyOnce(t *testing.T) {
+	repoDir, poolDir := setupLocalRepo(t)
+	lease, err := AcquireLeaseInfo(repoDir, poolDir, 1, nil, "automation-A")
+	if err != nil {
+		t.Fatalf("AcquireLeaseInfo failed: %v", err)
+	}
+
+	enteredBoundary := make(chan struct{})
+	allowReset := make(chan struct{})
+	secondStarted := make(chan struct{})
+	results := make(chan error, 2)
+	var preparationCalls atomic.Int32
+	preconditions := ReleasePreconditions{
+		ExpectedLeaseID:     &lease.LeaseID,
+		ExpectedLeaseHolder: &lease.LeaseHolder,
+	}
+	release := func() {
+		results <- ReleaseConditional(poolDir, lease.Path, preconditions, func() error {
+			if preparationCalls.Add(1) == 1 {
+				close(enteredBoundary)
+				<-allowReset
+			}
+			return nil
+		})
+	}
+
+	go release()
+	<-enteredBoundary
+	go func() {
+		close(secondStarted)
+		release()
+	}()
+	<-secondStarted
+	close(allowReset)
+
+	var succeeded, refused int
+	for range 2 {
+		err := <-results
+		switch {
+		case err == nil:
+			succeeded++
+		case errors.Is(err, ErrLeasePreconditionFailed):
+			refused++
+		default:
+			t.Fatalf("unexpected concurrent release error: %v", err)
+		}
+	}
+	if succeeded != 1 || refused != 1 {
+		t.Fatalf("concurrent releases: succeeded=%d refused=%d, want exactly one each", succeeded, refused)
+	}
+	if preparationCalls.Load() != 1 {
+		t.Fatalf("release preparation ran %d times, want 1", preparationCalls.Load())
+	}
+
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(state.Worktrees) != 1 || state.Worktrees[0].Leased {
+		t.Fatalf("expected lease released exactly once, got %#v", state.Worktrees)
+	}
+}
+
 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/state.go b/internal/pool/state.go
index 995c464..7a97f69 100644
--- a/internal/pool/state.go
+++ b/internal/pool/state.go
@@ -2,6 +2,7 @@ package pool
 
 import (
 	"crypto/rand"
+	"encoding/hex"
 	"encoding/json"
 	"fmt"
 	"os"
@@ -22,12 +23,24 @@ type WorktreeEntry struct {
 	// 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"`
+	// LeaseID is an immutable identity for one acquisition. It is empty only
+	// when loading state written by a Treehouse version that predates lease IDs
+	// or when conservatively recovering a corrupt state file.
+	LeaseID string `json:"lease_id,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,omitzero"`
 }
 
+func newLeaseID() (string, error) {
+	var id [16]byte
+	if _, err := rand.Read(id[:]); err != nil {
+		return "", fmt.Errorf("generating lease identity: %w", err)
+	}
+	return hex.EncodeToString(id[:]), nil
+}
+
 type State struct {
 	Worktrees []WorktreeEntry `json:"worktrees"`
 }
diff --git a/internal/pool/state_test.go b/internal/pool/state_test.go
index a2fa6a0..a491030 100644
--- a/internal/pool/state_test.go
+++ b/internal/pool/state_test.go
@@ -27,6 +27,35 @@ func TestWriteState_RoundTrip(t *testing.T) {
 	}
 }
 
+func TestReadState_LoadsPreIdentityLease(t *testing.T) {
+	poolDir := t.TempDir()
+	stateJSON := `{
+  "worktrees": [{
+    "name": "1",
+    "path": "legacy-worktree",
+    "created_at": "2026-07-20T12:00:00Z",
+    "leased": true,
+    "lease_holder": "legacy-automation",
+    "leased_at": "2026-07-20T12:01:00Z"
+  }]
+}`
+	if err := os.WriteFile(stateFilePath(poolDir), []byte(stateJSON), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	state, err := ReadState(poolDir)
+	if err != nil {
+		t.Fatalf("ReadState rejected pre-identity lease: %v", err)
+	}
+	if len(state.Worktrees) != 1 {
+		t.Fatalf("ReadState returned %d entries, want 1", len(state.Worktrees))
+	}
+	lease := state.Worktrees[0]
+	if !lease.Leased || lease.LeaseID != "" || lease.LeaseHolder != "legacy-automation" || lease.LeasedAt.IsZero() {
+		t.Fatalf("pre-identity lease loaded incorrectly: %#v", lease)
+	}
+}
+
 // TestWriteState_LeavesNoTempFileBehind guards the temp-then-rename approach:
 // a successful write must not leave its staging file lying around next to the
 // real state file.

From 7df247f2b1e57a5ae6044ddb62daf0554a0846d4 Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 20 Jul 2026 12:17:45 -0700
Subject: [PATCH 2/3] no-mistakes(review): Avoid holding pool lock during
 conditional return prompts

---
 cmd/e2e_test.go       | 77 +++++++++++++++++++++++++++++++++++++++++++
 cmd/return_cmd.go     | 24 ++++++++++++--
 internal/pool/pool.go | 48 ++++++++++++++++++---------
 3 files changed, 130 insertions(+), 19 deletions(-)

diff --git a/cmd/e2e_test.go b/cmd/e2e_test.go
index 16ae44b..4980cb9 100644
--- a/cmd/e2e_test.go
+++ b/cmd/e2e_test.go
@@ -2,8 +2,10 @@ package cmd
 
 import (
 	"bytes"
+	"context"
 	"encoding/hex"
 	"encoding/json"
+	"io"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -752,6 +754,81 @@ func TestReturnConditionalLeaseIdentityLifecycle(t *testing.T) {
 	}
 }
 
+func TestReturnConditionalDirtyPromptDoesNotHoldPoolLock(t *testing.T) {
+	repoDir, homeDir := setupTestRepo(t)
+	lease := acquireLeaseJSON(t, repoDir, homeDir, "holder-A")
+	if err := os.WriteFile(filepath.Join(lease.Path, "dirty.txt"), []byte("dirty\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	returnProcess := exec.Command(treehouseBin, "return", "--if-lease-id", lease.LeaseID, lease.Path)
+	returnProcess.Dir = repoDir
+	returnProcess.Env = buildEnv(homeDir)
+	stdin, err := returnProcess.StdinPipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	stderr, err := returnProcess.StderrPipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := returnProcess.Start(); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if returnProcess.ProcessState == nil {
+			_ = returnProcess.Process.Kill()
+			_ = returnProcess.Wait()
+		}
+	})
+
+	promptRead := make(chan error, 1)
+	go func() {
+		promptRead <- readUntilSuffix(stderr, "[Y/n] ")
+	}()
+	select {
+	case err := <-promptRead:
+		if err != nil {
+			t.Fatalf("failed to read return prompt: %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("conditional return did not prompt")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	statusProcess := exec.CommandContext(ctx, treehouseBin, "status")
+	statusProcess.Dir = repoDir
+	statusProcess.Env = buildEnv(homeDir)
+	if output, err := statusProcess.CombinedOutput(); err != nil {
+		t.Fatalf("status blocked while return awaited confirmation: %v: %s", err, output)
+	}
+
+	if _, err := io.WriteString(stdin, "n\n"); err != nil {
+		t.Fatal(err)
+	}
+	if err := stdin.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := returnProcess.Wait(); err != nil {
+		t.Fatalf("aborted return failed: %v", err)
+	}
+}
+
+func readUntilSuffix(reader io.Reader, suffix string) error {
+	buffer := make([]byte, 0, len(suffix))
+	byteBuffer := make([]byte, 1)
+	for {
+		if _, err := io.ReadFull(reader, byteBuffer); err != nil {
+			return err
+		}
+		buffer = append(buffer, byteBuffer[0])
+		if bytes.HasSuffix(buffer, []byte(suffix)) {
+			return nil
+		}
+	}
+}
+
 func acquireLeaseJSON(t *testing.T, repoDir, homeDir, holder string) leaseJSONResult {
 	t.Helper()
 	stdout, stderr, code := runTreehouse(t, repoDir, homeDir, nil, "get", "--lease", "--lease-holder", holder, "--json")
diff --git a/cmd/return_cmd.go b/cmd/return_cmd.go
index d7bcf28..a3dc049 100644
--- a/cmd/return_cmd.go
+++ b/cmd/return_cmd.go
@@ -55,9 +55,15 @@ var returnCmd = &cobra.Command{
 			if cmd.Flags().Changed("if-lease-holder") {
 				preconditions.ExpectedLeaseHolder = &returnIfLeaseHolder
 			}
-			err = pool.ReleaseConditional(poolDir, wtPath, preconditions, func() error {
-				return prepareWorktreeReturn(wtPath)
-			})
+			err = pool.ValidateReleasePreconditions(poolDir, wtPath, preconditions)
+			if err == nil {
+				err = confirmWorktreeReturn(wtPath)
+			}
+			if err == nil {
+				err = pool.ReleaseConditional(poolDir, wtPath, preconditions, func() error {
+					return finalizeWorktreeReturn(wtPath)
+				})
+			}
 		} else {
 			err = prepareWorktreeReturn(wtPath)
 			if err == nil {
@@ -85,6 +91,13 @@ func init() {
 }
 
 func prepareWorktreeReturn(wtPath string) error {
+	if err := confirmWorktreeReturn(wtPath); err != nil {
+		return err
+	}
+	return finalizeWorktreeReturn(wtPath)
+}
+
+func confirmWorktreeReturn(wtPath string) error {
 	if !returnForce {
 		dirty, _ := git.IsDirty(wtPath)
 		if dirty {
@@ -93,7 +106,12 @@ func prepareWorktreeReturn(wtPath string) error {
 				return errReturnAborted
 			}
 		}
+	}
+	return nil
+}
 
+func finalizeWorktreeReturn(wtPath string) error {
+	if !returnForce {
 		if err := git.DetachWorktree(wtPath); err != nil {
 			return fmt.Errorf("failed to detach worktree HEAD: %w", err)
 		}
diff --git a/internal/pool/pool.go b/internal/pool/pool.go
index f6219bd..85fbbe8 100644
--- a/internal/pool/pool.go
+++ b/internal/pool/pool.go
@@ -232,6 +232,19 @@ func Release(poolDir, worktreePath string) error {
 	return ReleaseConditional(poolDir, worktreePath, ReleasePreconditions{}, nil)
 }
 
+// ValidateReleasePreconditions checks that a managed worktree still matches
+// the requested lease without performing any release effects.
+func ValidateReleasePreconditions(poolDir, worktreePath string, preconditions ReleasePreconditions) error {
+	return WithStateLock(poolDir, func() error {
+		state, err := ReadState(poolDir)
+		if err != nil {
+			return err
+		}
+		_, err = releasableWorktree(&state, worktreePath, preconditions)
+		return err
+	})
+}
+
 // ReleaseConditional verifies any lease preconditions, runs beforeReset, resets
 // the worktree, and clears its reservation while holding one state lock. The
 // callback is invoked only after all preconditions match and runs under that
@@ -251,22 +264,8 @@ func ReleaseConditional(poolDir, worktreePath string, preconditions ReleasePreco
 			return err
 		}
 
-		entryIndex := -1
-		for i := range state.Worktrees {
-			if state.Worktrees[i].Path == worktreePath {
-				entryIndex = i
-				break
-			}
-		}
-		if entryIndex < 0 {
-			return fmt.Errorf("worktree %s is not managed by treehouse", worktreePath)
-		}
-
-		wt := &state.Worktrees[entryIndex]
-		if wt.Destroying {
-			return fmt.Errorf("worktree %s is being destroyed", worktreePath)
-		}
-		if err := validateReleasePreconditions(*wt, preconditions); err != nil {
+		wt, err := releasableWorktree(&state, worktreePath, preconditions)
+		if err != nil {
 			return err
 		}
 		if beforeReset != nil {
@@ -285,6 +284,23 @@ func ReleaseConditional(poolDir, worktreePath string, preconditions ReleasePreco
 	})
 }
 
+func releasableWorktree(state *State, worktreePath string, preconditions ReleasePreconditions) (*WorktreeEntry, error) {
+	for i := range state.Worktrees {
+		wt := &state.Worktrees[i]
+		if wt.Path != worktreePath {
+			continue
+		}
+		if wt.Destroying {
+			return nil, fmt.Errorf("worktree %s is being destroyed", worktreePath)
+		}
+		if err := validateReleasePreconditions(*wt, preconditions); err != nil {
+			return nil, err
+		}
+		return wt, nil
+	}
+	return nil, fmt.Errorf("worktree %s is not managed by treehouse", worktreePath)
+}
+
 func validateReleasePreconditions(wt WorktreeEntry, preconditions ReleasePreconditions) error {
 	if preconditions.ExpectedLeaseID == nil && preconditions.ExpectedLeaseHolder == nil {
 		return nil

From d97c42b9fec66b246841acb6f15091a371b6d795 Mon Sep 17 00:00:00 2001
From: kunchenguid <kun@kunchenguid.com>
Date: Mon, 20 Jul 2026 12:24:10 -0700
Subject: [PATCH 3/3] no-mistakes(document): Clarify lease JSON output
 documentation

---
 .../lease-cli-transcript.md                   | 65 +++++++++++++++++++
 README.md                                     |  2 +-
 cmd/get.go                                    | 16 ++---
 internal/pool/pool.go                         |  4 +-
 4 files changed, 76 insertions(+), 11 deletions(-)
 create mode 100644 .no-mistakes/evidence/fm/treehouse-stable-lease-identity-b1/lease-cli-transcript.md

diff --git a/.no-mistakes/evidence/fm/treehouse-stable-lease-identity-b1/lease-cli-transcript.md b/.no-mistakes/evidence/fm/treehouse-stable-lease-identity-b1/lease-cli-transcript.md
new file mode 100644
index 0000000..baec4c5
--- /dev/null
+++ b/.no-mistakes/evidence/fm/treehouse-stable-lease-identity-b1/lease-cli-transcript.md
@@ -0,0 +1,65 @@
+# Stable lease identity CLI validation
+
+This transcript came from the compiled `treehouse` binary in a fresh local Git repository with an isolated `HOME`. It exercises the end-user JSON and conditional-return surfaces.
+
+## 1. Allocate a lease as `automation-A`
+
+```json
+{"path":"/tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo","lease_id":"4d6e581c9889f539cf3defb32209c991","lease_holder":"automation-A","leased_at":"2026-07-20T12:20:27.465416-07:00"}
+```
+
+## 2. Status exposes the same identity
+
+```json
+[{"name":"1","path":"/tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo","status":"leased","lease_id":"4d6e581c9889f539cf3defb32209c991","lease_holder":"automation-A","leased_at":"2026-07-20T12:20:27.465416-07:00","processes":[]}]
+```
+
+## 3. A wrong identity is rejected without releasing the lease
+
+Command exited 1:
+
+```text
+failed to return worktree: lease precondition failed: lease identity does not match worktree /tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo
+```
+
+Status still reports the original lease:
+
+```json
+[{"name":"1","path":"/tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo","status":"leased","lease_id":"4d6e581c9889f539cf3defb32209c991","lease_holder":"automation-A","leased_at":"2026-07-20T12:20:27.465416-07:00","processes":[]}]
+```
+
+## 4. The correct identity releases successfully
+
+```text
+🌳 Worktree returned to pool.
+```
+
+## 5. Same path and holder get a new identity
+
+Old path:
+
+```text
+/tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo
+```
+
+New allocation:
+
+```json
+{"path":"/tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo","lease_id":"42e716b76d721ab9212dba38c062f450","lease_holder":"automation-A","leased_at":"2026-07-20T12:20:27.800304-07:00"}
+```
+
+Identity comparison: `ids_differ=true`.
+
+## 6. The old identity cannot release the newer same-holder lease
+
+Command exited 1:
+
+```text
+failed to return worktree: lease precondition failed: lease identity does not match worktree /tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo
+```
+
+Status confirms that the newer lease remains current after the stale ABA attempt:
+
+```json
+[{"name":"1","path":"/tmp/treehouse-lease-validation.IP9UTX/home/.treehouse/repo-f547e7/1/repo","status":"leased","lease_id":"42e716b76d721ab9212dba38c062f450","lease_holder":"automation-A","leased_at":"2026-07-20T12:20:27.800304-07:00","processes":[]}]
+```
diff --git a/README.md b/README.md
index 1f74a24..204e577 100644
--- a/README.md
+++ b/README.md
@@ -194,7 +194,7 @@ 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).
+It acquires a worktree exactly like `get`, but instead of opening a subshell it marks the worktree **leased** in treehouse's persistent state. By default it prints only the worktree's absolute path to stdout; `--json` prints the lease allocation instead. Every human-facing message goes to stderr, so either output mode 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.
 A bulk `treehouse destroy <pool> --all` never removes it either; only naming its exact path with `treehouse destroy <path> --include-leased --yes` will.
diff --git a/cmd/get.go b/cmd/get.go
index f60d5a8..8d82fb7 100644
--- a/cmd/get.go
+++ b/cmd/get.go
@@ -30,10 +30,11 @@ var getCmd = &cobra.Command{
 	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>'.`,
+worktree and marks it leased in persistent state. By default it prints only the
+absolute path to stdout; add --json for the lease identity and metadata. 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,
 }
 
@@ -111,10 +112,9 @@ 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.
+// getLeaseRunE performs a non-interactive, durable acquire. It writes either the
+// worktree path or the requested JSON allocation to stdout and routes every
+// human-facing message to stderr, keeping both output modes machine-readable.
 func getLeaseRunE(repoRoot, poolDir string, cfg config.Config) error {
 	holder := getLeaseHolder
 	if holder == "" {
diff --git a/internal/pool/pool.go b/internal/pool/pool.go
index 85fbbe8..0e79e9e 100644
--- a/internal/pool/pool.go
+++ b/internal/pool/pool.go
@@ -52,7 +52,7 @@ type acquireOptions struct {
 	// 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.
+	// hook stdout to stderr so it cannot contaminate machine-readable CLI output.
 	hookStdout io.Writer
 	hookStderr io.Writer
 }
@@ -72,7 +72,7 @@ func Acquire(repoRoot, poolDir string, poolSize int, postCreate []string) (strin
 // 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.
+// can emit machine-readable allocation output without hook output on stdout.
 func AcquireLease(repoRoot, poolDir string, poolSize int, postCreate []string, holder string) (string, error) {
 	lease, err := AcquireLeaseInfo(repoRoot, poolDir, poolSize, postCreate, holder)
 	return lease.Path, err