Auto-pick base port for worktrees and drop CLI base port argument

Author: tjementum

.claude/skills/aspire-restart/SKILL.md

@@ -6,7 +6,7 @@ description: Start or restart the .NET Aspire AppHost via the developer CLI. Alw
 # Restart Aspire
 
 ```bash
-dotnet run --project developer-cli -- restart [<basePort>]
+dotnet run --project developer-cli -- restart
 ```
 
 Use `developer-cli` exactly as written - do not expand to an absolute worktree path.
@@ -15,7 +15,6 @@ Stops any running Aspire AppHost and starts a fresh instance. Detached by defaul
 
 Always use `restart`, even when nothing is running yet. It is a no-op when Aspire is not up, and the safe default in every other case. Never use the developer CLI's `run` command, `aspire run`, or `aspire restart`.
 
-- `<basePort>` - optional positional argument; written to `.workspace/port.txt` before Aspire starts
 - `--public-url <url>` - set `PUBLIC_URL` (e.g. an ngrok URL)
 
 ## When to use
@@ -25,10 +24,9 @@ Always use `restart`, even when nothing is running yet. It is a no-op when Aspir
 - When hot reload breaks or stops picking up changes.
 - Before running e2e tests on a fresh stack.
 
-## Picking the base port
+## Port allocation
 
-- In the git root: omit `<basePort>` (uses the default).
-- In a worktree: on the first start, pick the first free port from `10000`, `11000`, `12000`, `13000` (`lsof -i :<port>` on macOS/Linux, `netstat -ano | findstr :<port>` on Windows). Keep using that port for the lifetime of the worktree - never change it after.
+Fully automatic. On a fresh checkout the developer CLI bootstraps `.workspace/port.txt`: the root gets the default base port; worktrees scan a fixed list of candidates and pick the first one whose ports are all free. Once written, the file is the authoritative allocation for the lifetime of the checkout.
 
 ## Output is fire-and-forget
 

application/shared-kernel/SharedKernel/Configuration/PortAllocation.cs

@@ -1,8 +1,13 @@
+using System.Net;
+using System.Net.Sockets;
+
 namespace SharedKernel.Configuration;
 
 // Single source of truth for the local development port allocation. Reads .workspace/port.txt
-// (single integer, whitespace-tolerant). If the file is missing, self-bootstraps with the default
-// base port so the first run on a fresh checkout just works. Throws on a present-but-invalid file.
+// (single integer, whitespace-tolerant). If the file is missing, self-bootstraps: the root
+// checkout gets the default base port; a worktree scans a fixed list of candidate base ports
+// and picks the first one whose ports are all free locally. Once written, port.txt is the
+// authoritative allocation for the lifetime of the checkout. Throws on a present-but-invalid file.
 public sealed record PortAllocation(int BasePort)
 {
     private const int DefaultBasePort = 9000;
@@ -11,6 +16,9 @@ public sealed record PortAllocation(int BasePort)
 
     private const string PortFileName = "port.txt";
 
+    // Worktrees scan these in order and pick the first base port whose full allocation is free.
+    private static readonly int[] WorktreeCandidateBasePorts = [9100, 9200, 9300, 9400, 9500, 9600, 9700, 9800, 9900];
+
     public int AppGateway => BasePort;
 
     public int Aspire => BasePort + 1;
@@ -74,9 +82,12 @@ public static PortAllocation LoadFrom(string repositoryRoot)
 
         if (!File.Exists(portFilePath))
         {
+            var bootstrapPort = IsWorktree(repositoryRoot)
+                ? FindFreeBasePortForWorktree()
+                : DefaultBasePort;
             Directory.CreateDirectory(workspaceDirectory);
-            File.WriteAllText(portFilePath, $"{DefaultBasePort}{Environment.NewLine}");
-            return new PortAllocation(DefaultBasePort);
+            File.WriteAllText(portFilePath, $"{bootstrapPort}{Environment.NewLine}");
+            return new PortAllocation(bootstrapPort);
         }
 
         var content = File.ReadAllText(portFilePath).Trim();
@@ -90,28 +101,45 @@ public static PortAllocation LoadFrom(string repositoryRoot)
         return new PortAllocation(basePort);
     }
 
-    // True if .workspace/port.txt already exists -- distinguishes a fresh worktree from a configured one.
+    // True if .workspace/port.txt already exists -- distinguishes a fresh checkout from a configured one.
     public static bool PortFileExists(string repositoryRoot)
     {
         var portFilePath = Path.Combine(repositoryRoot, WorkspaceDirectoryName, PortFileName);
         return File.Exists(portFilePath);
     }
 
-    // Atomically writes the base port to .workspace/port.txt under the given repository root.
-    // Callers (e.g., the developer CLI's positional base-port argument on run/restart) use this to
-    // update the file before any code path lazily loads PortAllocation -- otherwise the lazy load
-    // would race with the write and could bootstrap with the default port.
-    public static void WriteBasePort(string repositoryRoot, int basePort)
+    // .git is a directory in the root checkout and a file in git worktrees.
+    private static bool IsWorktree(string repositoryRoot)
     {
-        if (basePort <= 0) throw new ArgumentOutOfRangeException(nameof(basePort), basePort, "Base port must be a positive integer.");
+        return File.Exists(Path.Combine(repositoryRoot, ".git"));
+    }
 
-        var workspaceDirectory = Path.Combine(repositoryRoot, WorkspaceDirectoryName);
-        var portFilePath = Path.Combine(workspaceDirectory, PortFileName);
-        var temporaryFilePath = portFilePath + ".tmp";
+    private static int FindFreeBasePortForWorktree()
+    {
+        foreach (var candidate in WorktreeCandidateBasePorts)
+        {
+            var allocation = new PortAllocation(candidate);
+            if (allocation.AllPorts.All(IsTcpPortFree)) return candidate;
+        }
 
-        Directory.CreateDirectory(workspaceDirectory);
-        File.WriteAllText(temporaryFilePath, $"{basePort}{Environment.NewLine}");
-        File.Move(temporaryFilePath, portFilePath, true);
+        throw new InvalidOperationException(
+            $"No free base port available for this worktree. Tried: {string.Join(", ", WorktreeCandidateBasePorts)}."
+        );
+    }
+
+    private static bool IsTcpPortFree(int port)
+    {
+        try
+        {
+            var listener = new TcpListener(IPAddress.Loopback, port);
+            listener.Start();
+            listener.Stop();
+            return true;
+        }
+        catch (SocketException)
+        {
+            return false;
+        }
     }
 
     private static string FindRepositoryRoot(string startDirectory)

developer-cli/Commands/ClaudeCommand/SendInterruptSignalCommand.cs

@@ -4,9 +4,8 @@ namespace DeveloperCli.Commands.ClaudeCommand;
 
 internal sealed class SendInterruptSignalCommand : Command
 {
-    private readonly Option<string> _teamOption = new("--team", "-t") { Description = "Team name", Required = true };
-
     private readonly Option<string> _agentOption = new("--agent", "-a") { Description = "Target agent name", Required = true };
+    private readonly Option<string> _teamOption = new("--team", "-t") { Description = "Team name", Required = true };
 
     public SendInterruptSignalCommand() : base("send-interrupt-signal", "Send an interrupt signal to a team agent")
     {

developer-cli/Commands/RestartCommand.cs

@@ -11,38 +11,32 @@ public class RestartCommand : Command
 {
     public RestartCommand() : base("restart", "Stops any running Aspire AppHost and starts a fresh instance")
     {
-        var basePortArgument = new Argument<int?>("basePort") { Description = "Optional base port. If provided, written to .workspace/port.txt before Aspire starts.", DefaultValueFactory = _ => null };
         var watchOption = new Option<bool>("--watch", "-w") { Description = "Enable watch mode for hot reload" };
         var attachOption = new Option<bool>("--attach", "-a") { Description = "Keep the CLI process attached to the Aspire process (detached is the default)" };
         var publicUrlOption = new Option<string?>("--public-url") { Description = "Set the PUBLIC_URL environment variable for the app (e.g., https://example.ngrok-free.app)" };
 
-        Arguments.Add(basePortArgument);
         Options.Add(watchOption);
         Options.Add(attachOption);
         Options.Add(publicUrlOption);
 
         SetAction(parseResult => Execute(
-                parseResult.GetValue(basePortArgument),
                 parseResult.GetValue(watchOption),
                 parseResult.GetValue(attachOption),
                 parseResult.GetValue(publicUrlOption)
             )
         );
     }
 
-    private static void Execute(int? basePort, bool watch, bool attach, string? publicUrl)
+    private static void Execute(bool watch, bool attach, string? publicUrl)
     {
         Prerequisite.Ensure(Prerequisite.Dotnet, Prerequisite.Node, Prerequisite.Docker);
 
-        // Skip stop in a fresh worktree (no port.txt) -- nothing to stop, and the check would otherwise false-positive on another worktree's stack.
+        // Skip stop in a fresh checkout (no port.txt) -- nothing to stop, and the check would otherwise false-positive on another stack.
         if (PortAllocation.PortFileExists(Configuration.SourceCodeFolder) && RunCommand.IsAspireRunning())
         {
-            // Stop on the OLD port before writing the new one; otherwise stop would look at the new port and miss the running old stack.
             RunCommand.StopAspire();
         }
 
-        RunCommand.WriteBasePortIfProvided(basePort);
-
         RunCommand.CheckForPortConflicts();
 
         RunCommand.StartAspireAppHost(watch, attach, publicUrl);

developer-cli/Commands/RunCommand.cs

@@ -13,18 +13,15 @@ public class RunCommand : Command
 {
     public RunCommand() : base("run", "Runs Aspire AppHost (use --watch for hot reload)")
     {
-        var basePortArgument = new Argument<int?>("basePort") { Description = "Optional base port. If provided, written to .workspace/port.txt before Aspire starts.", DefaultValueFactory = _ => null };
         var watchOption = new Option<bool>("--watch", "-w") { Description = "Enable watch mode for hot reload" };
         var attachOption = new Option<bool>("--attach", "-a") { Description = "Keep the CLI process attached to the Aspire process (detached is the default)" };
         var publicUrlOption = new Option<string?>("--public-url") { Description = "Set the PUBLIC_URL environment variable for the app (e.g., https://example.ngrok-free.app)" };
 
-        Arguments.Add(basePortArgument);
         Options.Add(watchOption);
         Options.Add(attachOption);
         Options.Add(publicUrlOption);
 
         SetAction(parseResult => Execute(
-                parseResult.GetValue(basePortArgument),
                 parseResult.GetValue(watchOption),
                 parseResult.GetValue(attachOption),
                 parseResult.GetValue(publicUrlOption)
@@ -34,9 +31,6 @@ public class RunCommand : Command
 
     // The CLI binary is published outside the repo, so PortAllocation.Load (which walks up from
     // AppContext.BaseDirectory) cannot find the repo. Use the CLI's known SourceCodeFolder instead.
-    // Re-read on every access so a run/restart invocation with a positional base port picks up the
-    // freshly written .workspace/port.txt without any cached PortAllocation lingering from earlier
-    // in the call.
     internal static PortAllocation Ports => PortAllocation.LoadFrom(Configuration.SourceCodeFolder);
 
     internal static int AspirePort => Ports.Aspire;
@@ -45,37 +39,24 @@ public class RunCommand : Command
 
     internal static int ResourceServicePort => Ports.ResourceService;
 
-    private static void Execute(int? basePort, bool watch, bool attach, string? publicUrl)
+    private static void Execute(bool watch, bool attach, string? publicUrl)
     {
         Prerequisite.Ensure(Prerequisite.Dotnet, Prerequisite.Node, Prerequisite.Docker);
 
-        // Refuse if Aspire is already on the currently configured port -- updating port.txt now would orphan the running stack.
+        // Refuse if Aspire is already on the currently configured port.
         // Skipped in a fresh worktree (no port.txt) where the check would false-positive on another worktree's stack.
         if (PortAllocation.PortFileExists(Configuration.SourceCodeFolder) && IsAspireRunning())
         {
             var alias = Configuration.AliasName;
-            var message = basePort is null
-                ? $"Aspire AppHost is already running on port {AspirePort}. Run '{alias} stop' to stop it or '{alias} restart' to start a fresh instance."
-                : $"Aspire AppHost is already running on port {AspirePort}. Run '{alias} stop' first or use '{alias} restart {basePort}' to switch.";
-            AnsiConsole.MarkupLine($"[yellow]{message}[/]");
+            AnsiConsole.MarkupLine($"[yellow]Aspire AppHost is already running on port {AspirePort}. Run '{alias} stop' to stop it or '{alias} restart' to start a fresh instance.[/]");
             Environment.Exit(1);
         }
 
-        WriteBasePortIfProvided(basePort);
-
         CheckForPortConflicts();
 
         StartAspireAppHost(watch, attach, publicUrl);
     }
 
-    internal static void WriteBasePortIfProvided(int? basePort)
-    {
-        if (basePort is null) return;
-
-        PortAllocation.WriteBasePort(Configuration.SourceCodeFolder, basePort.Value);
-        AnsiConsole.MarkupLine($"[blue]Set base port to {basePort.Value}.[/]");
-    }
-
     internal static bool IsAspireRunning()
     {
         // Check the main Aspire port