From eb420dabff5e25a132e28d7676202801ac907239 Mon Sep 17 00:00:00 2001
From: "Tommy D. Rossi" <beats.by.morse@gmail.com>
Date: Wed, 25 Feb 2026 17:14:29 +0100
Subject: [PATCH] docs: verify relay port cleanup in local CLI instructions

Replace the macOS kill one-liner with a zsh-safe array pattern and add explicit post-kill verification commands for macOS and Windows. This prevents false positives where port 19988 remains occupied after an attempted shutdown.
---
 PLAYWRITER_AGENTS.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/PLAYWRITER_AGENTS.md b/PLAYWRITER_AGENTS.md
index 59c0dfc..075b39c 100644
--- a/PLAYWRITER_AGENTS.md
+++ b/PLAYWRITER_AGENTS.md
@@ -51,10 +51,15 @@ to test CLI changes without publishing:
 
 ```bash
  # mac/linux: kill any existing relay on 19988
- lsof -ti :19988 | xargs kill
+ PIDS=($(lsof -ti :19988))
+ if [ ${#PIDS[@]} -gt 0 ]; then kill "${PIDS[@]}"; fi
+ # verify port is free (must print nothing)
+ lsof -ti :19988
 
  # windows (powershell): kill any existing relay on 19988
  Get-NetTCPConnection -LocalPort 19988 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
+ # verify port is free (must print nothing)
+ Get-NetTCPConnection -LocalPort 19988 -ErrorAction SilentlyContinue
 
  tsx playwriter/src/cli.ts -s 1 -e "await page.goto('https://example.com')"
  tsx playwriter/src/cli.ts -s 1 -e "console.log(await snapshot({ page }))"