Don't allow forceable removal

Author: johnml1135

scripts/git-utilities.ps1

@@ -172,13 +172,3 @@ function Test-GitBranchExists {
   return ($output.Count -gt 0)
 }
 
-function Reset-GitBranchToRef {
-  [CmdletBinding()]
-  param(
-    [Parameter(Mandatory=$true)][string]$Branch,
-    [Parameter(Mandatory=$true)][string]$Ref
-  )
-
-  # Ensures the agent branch is a mirror of the desired base ref.
-  Invoke-GitSafe @('branch','-f',$Branch,$Ref) -Quiet
-}

scripts/multi-agent-containers-workflow.md

@@ -62,13 +62,16 @@ The script will:
    - `-OpenVSCode` - launches a VS Code window per agent with `FW_AGENT_CONTAINER` set
 
 The script will:
-- Create worktrees at `...\worktrees\agent-1..N` with branches `agents/agent-1..N`
+- Create NEW worktrees at `...\worktrees\agent-1..N` with branches `agents/agent-1..N` from BaseRef
+- **SKIP existing worktrees** (preserves your work - never resets or modifies existing worktrees)
 - Build or reuse the `fw-build:ltsc2022` Windows image
-- Start containers `fw-agent-1..N` with per-agent NuGet caches
-- Generate `.vscode/tasks.json` wired to the matching container
+- Start containers `fw-agent-1..N` with per-agent NuGet caches (skipped for existing worktrees)
+- Generate `.vscode/tasks.json` wired to the matching container (only for new worktrees)
 - Generate `.vscode/settings.json` with unique colors to keep agent windows visually distinct
 - Optionally open each worktree in a new VS Code window
 
+**IMPORTANT**: This script **NEVER modifies existing worktrees** to prevent data loss. If you want to reset a worktree to a different branch, use `tear-down-agents.ps1 -RemoveWorktrees` first, then re-run spin-up.
+
 3. Work per agent
 
 - Open the worktree folder in VS Code (one window per agent)
@@ -84,6 +87,16 @@ All registry and COM operations occur inside the container, isolated from your h
   - `gh pr create -H agents/agent-1 -B release/9.3 -t "..." -b "..."`
 - Avoid running Git inside the container for that worktree to prevent file locking.
 
+**Branch reuse behavior**: If `agents/agent-N` branches already exist, spin-up will:
+- Create worktrees attached to the existing branches at their current commits
+- **NOT** reset branches to BaseRef automatically
+- Let you manually sync branches if needed:
+  ```powershell
+  cd worktrees\agent-1
+  git fetch origin
+  git merge origin/release/9.3  # or git reset --hard origin/release/9.3
+  ```
+
 ## Performance and limits
 
 - Avoid building all 5 agents simultaneously on a 32 GB machine; stagger builds or reduce msbuild parallelism
@@ -105,6 +118,26 @@ Remove containers, worktrees, agent branches, and per-agent NuGet caches:
   -RemoveWorktrees
 ```
 
+**IMPORTANT**: Tear-down will **ERROR and refuse to remove worktrees** that have uncommitted changes to prevent data loss. You'll see:
+```
+Worktree agent-1 has uncommitted changes at: C:\...\worktrees\agent-1
+
+To protect your work, tear-down will NOT remove this worktree.
+```
+
+To proceed, commit or stash your changes first:
+```powershell
+cd worktrees\agent-1
+git add .
+git commit -m "Work in progress"
+# Then re-run tear-down
+```
+
+Only use `-ForceRemoveDirty` if you're **certain** you want to discard uncommitted work:
+```powershell
+.\scripts\tear-down-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -RemoveWorktrees -ForceRemoveDirty
+```
+
 You can pass `-WorktreesRoot` if you placed worktrees outside the default path; otherwise the script respects `FW_WORKTREES_ROOT` when present.
 
 ## Notes
@@ -152,11 +185,25 @@ docker logs fw-agent-1  # Check container logs
 ```
 
 ### Worktree already exists
-The script safely reuses existing worktrees and containers. To start fresh:
+The script **preserves existing worktrees** and will skip them to prevent data loss. You'll see:
+```
+Worktree already exists: C:\...\worktrees\agent-1 (skipping - will not modify existing worktree)
+  Branch: agents/agent-1 (current state preserved)
+```
+
+To reset a worktree to a different branch or base ref:
 ```powershell
+# Option 1: Remove all worktrees and recreate fresh
 .\scripts\tear-down-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -Count 3 -RemoveWorktrees
+
+# Option 2: Manually delete specific worktree, then re-run spin-up
+Remove-Item -Recurse -Force "C:\...\worktrees\agent-1"
+git worktree prune
+.\scripts\spin-up-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -Count 3
 ```
 
+**Never** try to force-reset worktrees - this was removed to prevent accidental data loss.
+
 ### Build fails inside container
 Verify the solution path is correct and accessible:
 ```powershell

scripts/spin-up-agents.ps1

@@ -6,20 +6,24 @@ Prereqs:
 - One primary clone on the host (e.g., C:\dev\FieldWorks)
 - PowerShell 5+ (Windows)
 
+IMPORTANT: This script NEVER modifies existing worktrees to prevent data loss.
+- Existing worktrees are preserved as-is (skipped)
+- New worktrees are created from the specified BaseRef
+- If you want to reset a worktree, manually delete it first or use tear-down-agents.ps1
+
 Typical use:
   $env:FW_WORKTREES_ROOT = "C:\dev\FieldWorks\worktrees"
 
   # Create agents based on current branch (default FieldWorks.proj build):
   .\scripts\spin-up-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -Count 3
 
-  # Or specify a different base branch:
+  # Or specify a different base branch (only affects NEW worktrees):
   .\scripts\spin-up-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -Count 3 -BaseRef origin/release/9.3
 
   # To prevent VS Code from opening automatically:
   .\scripts\spin-up-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -Count 3 -SkipOpenVSCode
 
-  # To forcibly clean orphaned worktree directories without prompting:
-  .\scripts\spin-up-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -Count 3 -ForceCleanup
+  # NOTE: -ForceCleanup parameter removed - use tear-down-agents.ps1 instead
 #>
 
 [CmdletBinding()]
@@ -34,7 +38,6 @@ param(
   [switch]$SkipVsCodeSetup,
   [switch]$ForceVsCodeSetup,
   [switch]$SkipOpenVSCode,
-  [switch]$ForceCleanup,
   [string]$ContainerMemory = "4g"
 )
 
@@ -232,22 +235,8 @@ function Ensure-Image {
   }
 }
 
-function Reset-AgentWorktree {
-  param(
-    [Parameter(Mandatory=$true)][string]$WorktreePath,
-    [Parameter(Mandatory=$true)][string]$ResetRef
-  )
-
-  if (-not (Test-Path -LiteralPath $WorktreePath)) { return }
-
-  Push-Location $WorktreePath
-  try {
-    Invoke-GitSafe @('reset','--hard',$ResetRef) -Quiet
-    Invoke-GitSafe @('clean','-xfd') -Quiet
-  } finally {
-    Pop-Location
-  }
-}
+# Reset-AgentWorktree function removed - we never modify existing worktrees
+# Existing worktrees are left untouched to prevent data loss
 
 function Clear-AgentDirectory {
   param(
@@ -298,30 +287,39 @@ function Ensure-Worktree {
     }
 
     if ($isRegistered -and $dirExists -and -not $isEmpty) {
-      # Worktree is registered and has content - reset to requested base
-      Write-Host "Worktree exists and is registered: $target"
-      Reset-AgentWorktree -WorktreePath $target -ResetRef $BaseRef
+      # Worktree exists with content - NEVER modify it to prevent data loss
+      Write-Host "Worktree already exists: $target (skipping - will not modify existing worktree)"
+      Write-Host "  Branch: $branch (current state preserved)"
+      # Skip to end - use existing worktree as-is
+      $resolvedTarget = (Resolve-Path -LiteralPath $target).Path
+      return @{ Branch = $branch; Path = $resolvedTarget; Skipped = $true }
     } elseif ($isRegistered -and (-not $dirExists -or $isEmpty)) {
       # Worktree is registered but directory is missing or empty - repair it
       Write-Host "Repairing worktree $target (directory missing or empty)..."
       Remove-GitWorktreePath -WorktreePath $thisWorktree.RawPath
       Prune-GitWorktreesNow
       $isRegistered = $false
       $branchWorktree = $null
-    } elseif (-not $isRegistered -and $dirExists) {
-      if (-not $ForceCleanup) {
-        throw "Directory $target exists but is not a registered worktree. Close any VS Code windows, run tear-down with -RemoveWorktrees, or rerun spin-up with -ForceCleanup to reset it."
-      }
-
-      Write-Host "Directory $target exists but is not registered; reinitializing worktree in place (contents will be reset)."
-      try {
-        Detach-GitWorktreeMetadata -WorktreePath $target | Out-Null
-      } catch {
-        $err = $_
-        Write-Warning "Failed to remove stale git metadata from ${target}: $err"
-      }
-
-      Clear-AgentDirectory -AgentPath $target
+    } elseif (-not $isRegistered -and $dirExists -and -not $isEmpty) {
+      # Directory exists with content but not a worktree - ERROR out
+      throw @"
+Directory $target exists but is not a registered git worktree.
+
+This could indicate:
+1. Leftover files from a previous worktree that wasn't cleaned up properly
+2. Manual files placed in the worktrees directory
+3. A corrupted worktree registration
+
+To fix this:
+- OPTION 1 (preserve content): Move the directory elsewhere, then rerun this script
+- OPTION 2 (discard content): Delete the directory manually, then rerun this script
+- OPTION 3 (force cleanup): Run: .\scripts\tear-down-agents.ps1 -RemoveWorktrees
+
+NEVER use -ForceCleanup as it will destroy your work without warning.
+"@
+    } elseif (-not $isRegistered -and $dirExists -and $isEmpty) {
+      # Directory exists but empty and not registered - safe to recreate
+      Write-Host "Directory $target exists but is empty; will create worktree here."
     }
 
     # Create worktree if needed
@@ -336,9 +334,8 @@ function Ensure-Worktree {
       $addArgs += $target
 
       if (Test-GitBranchExists -Branch $branch) {
-        Write-Host "Resetting $branch to $BaseRef before reuse..."
-        Reset-GitBranchToRef -Branch $branch -Ref $BaseRef
-        Write-Host "Creating worktree $target with existing branch $branch..."
+        Write-Host "Creating worktree $target with existing branch $branch (preserving current branch state)..."
+        Write-Host "  Note: Branch will remain at its current commit; use 'git merge' or 'git reset' in the worktree if you want to sync with $BaseRef"
         $addArgs += $branch
       } else {
         Write-Host "Creating worktree $target with new branch $branch from $BaseRef..."
@@ -353,10 +350,7 @@ function Ensure-Worktree {
     }
     Ensure-RelativeGitDir -WorktreePath $target -RepoRoot $RepoRoot -WorktreeName "agent-$Index"
     $resolvedTarget = (Resolve-Path -LiteralPath $target).Path
-
-    if (-not $isRegistered) {
-      Reset-AgentWorktree -WorktreePath $resolvedTarget -ResetRef $BaseRef
-    }
+    # Never reset worktrees - new worktrees are created at correct ref, existing ones are preserved
   } finally {
     Pop-Location
   }
@@ -595,6 +589,20 @@ $repoVsCodeSettings = Get-RepoVsCodeSettings -RepoRoot $RepoRoot
 $agents = @()
 for ($i=1; $i -le $Count; $i++) {
   $wt = Ensure-Worktree -Index $i
+
+  if ($wt.Skipped) {
+    Write-Host "Agent-$i: Using existing worktree (no changes made)"
+    $agents += [pscustomobject]@{
+      Index = $i
+      Worktree = $wt.Path
+      Branch = $wt.Branch
+      Container = "(existing)"
+      Theme = "(preserved)"
+      Status = "Skipped - existing worktree preserved"
+    }
+    continue
+  }
+
   $ct = Ensure-Container -Index $i -AgentPath $wt.Path -RepoRoot $RepoRoot -WorktreesRoot $WorktreesRoot
   Write-AgentConfig -AgentPath $wt.Path -SolutionRelPath $SolutionRelPath -Container $ct -RepoRoot $RepoRoot
   $colors = Get-AgentColors -Index $i
@@ -617,6 +625,7 @@ for ($i=1; $i -le $Count; $i++) {
     Branch = $wt.Branch
     Container = $ct.Name
     Theme = $colors.Name
+    Status = "Ready"
   }
 }
 

scripts/tear-down-agents.ps1

@@ -1,17 +1,21 @@
 <#
 Stop and remove fw-agent-* containers and optionally clean up agents/* caches.
-Worktrees themselves are preserved for reuse (we still warn about uncommitted changes
-unless -ForceRemoveDirty is specified).
+Worktrees themselves are preserved for reuse.
+
+SAFETY: This script will ERROR and refuse to remove worktrees that have uncommitted
+changes, preventing accidental data loss. Use -ForceRemoveDirty only if you're certain
+you want to discard uncommitted work.
 
 # Examples
 #   .\scripts\tear-down-agents.ps1 -RepoRoot "C:\dev\FieldWorks"
 #     (Stops all fw-agent-* containers but leaves worktrees/branches.)
 #
 #   .\scripts\tear-down-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -RemoveWorktrees -RemoveNuGetCaches
 #     (Also removes agents/agent-* worktrees, git branches, and per-agent NuGet caches.)
+#     (Will ERROR if any worktree has uncommitted changes.)
 #
 #   .\scripts\tear-down-agents.ps1 -RepoRoot "C:\dev\FieldWorks" -RemoveWorktrees -ForceRemoveDirty
-#     (Removes worktrees without prompting even if uncommitted changes exist.)
+#     (⚠️ DANGEROUS: Removes worktrees even with uncommitted changes - DATA LOSS!)
 #>
 
 [CmdletBinding()]
@@ -191,9 +195,22 @@ $removeCaches = $RemoveWorktrees -or $RemoveNuGetCaches
           if (Test-Path -LiteralPath $wtPath) {
             $hasChanges = Test-WorktreeHasUncommittedChanges -WorktreePath $wtPath
             if ($hasChanges -and -not $ForceRemoveDirty) {
-              Write-Warning "Worktree agent-$i has uncommitted changes; content will remain but tracking will be detached (use -ForceRemoveDirty to skip this warning)."
+              throw @"
+Worktree agent-$i has uncommitted changes at: $wtPath
+
+To protect your work, tear-down will NOT remove this worktree.
+
+Options:
+1. Commit or stash your changes in the worktree, then re-run tear-down
+2. Push your changes to a remote branch for safekeeping
+3. Use -ForceRemoveDirty to override (WARNING: This will DELETE uncommitted work)
+
+To check what's uncommitted:
+  cd '$wtPath'
+  git status
+"@
             }
-            Write-Host "Detaching worktree agent-$i while leaving $wtPath on disk."
+            Write-Host "Detaching worktree agent-$i (no uncommitted changes detected)."
           } else {
             Write-Host "Worktree agent-$i not found on disk; only detaching branch metadata."
           }