From 988038d165fcc97fd02abd952fdb365b0f64d8be Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Fri, 4 Sep 2026 14:13:31 -0700
Subject: [PATCH] docs(ports): note the ordering contract between the reuse
 split and the remember step

---
 src/main/ports/local-workspace-port-scan-state.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/main/ports/local-workspace-port-scan-state.ts b/src/main/ports/local-workspace-port-scan-state.ts
index 23718658eec..ee2029a4226 100644
--- a/src/main/ports/local-workspace-port-scan-state.ts
+++ b/src/main/ports/local-workspace-port-scan-state.ts
@@ -89,6 +89,7 @@ function listenerMetadataKey(port: RawListeningPort): string {
   return `${port.pid ?? 'unknown'}:${port.host}:${port.port}`
 }
 
+/** Call after partitionListenersNeedingMetadata: it consumes the reuse set that call recorded. */
 export function rememberListenerMetadata(ports: readonly RawListeningPort[]): void {
   const previous = lastListenerMetadata
   lastListenerMetadata = new Map()
@@ -112,6 +113,8 @@ export function rememberListenerMetadata(ports: readonly RawListeningPort[]): vo
 /**
  * Split listeners into those a previous scan already resolved and the pids still needing a probe.
  *
+ * Records which keys were reused; rememberListenerMetadata reads and clears that on the same scan.
+ *
  * Why: the metadata commands are the expensive half of a macOS scan, and a listener that is still
  * the same process on the same address has the same command line it had 30s ago. A remembered
  * entry is only trusted when the free `lsof -F c` process name and `-F d` socket identity from