vouchington-tooling 0.0.8 → 0.0.10

package/dist/gha-artifacts-cleanup/plan.mjs

@@ -0,0 +1,40 @@
+export function summarize(deleted) {
+    return {
+        deletedCount: deleted.length,
+        bytesFreed: deleted.reduce((total, artifact) => total + artifact.size_in_bytes, 0),
+    };
+}
+export function planRunDeletions(artifacts, classify) {
+    return artifacts.filter((artifact) => !artifact.expired && classify(artifact.name) === 'delete');
+}
+export function isSweepCandidate(artifact, cutoffIso, classify) {
+    return (!artifact.expired && artifact.created_at < cutoffIso && classify(artifact.name) === 'delete');
+}
+const MAX_CONSECUTIVE_EXPIRED_PAGES = 5;
+const MAX_PAGES = 150;
+export function shouldStopPaging(pageArtifacts, state) {
+    if (state.page >= MAX_PAGES)
+        return true;
+    if (pageArtifacts.length === 0)
+        return true;
+    return state.consecutiveExpiredPages >= MAX_CONSECUTIVE_EXPIRED_PAGES;
+}
+export function nextPagingState(pageArtifacts, state) {
+    const pageFullyExpired = pageArtifacts.every((artifact) => artifact.expired);
+    return {
+        page: state.page + 1,
+        consecutiveExpiredPages: pageFullyExpired ? state.consecutiveExpiredPages + 1 : 0,
+    };
+}
+export async function planSweepDeletions(candidates, getConclusion) {
+    const toDelete = [];
+    for (const artifact of candidates) {
+        const runId = artifact.workflow_run?.id;
+        if (runId == null)
+            continue;
+        const conclusion = await getConclusion(runId);
+        if (conclusion === 'success' || conclusion === 'cancelled')
+            toDelete.push(artifact);
+    }
+    return toDelete;
+}

package/dist/gha-selected-files/index.d.mts

@@ -0,0 +1,6 @@
+export declare function encodeSelectedFiles(files: readonly string[]): string;
+export declare const SELECTED_FILES_ENV_MAX_BYTES = 120000;
+export declare function selectedFilesExceedEnvBudget(files: readonly string[]): boolean;
+export declare function decodeSelectedFiles(raw: string | undefined | null): string[];
+export declare function formatMultilineOutput(key: string, value: string, createId?: () => string): string;
+export declare function writeSelectedFilesOutput(key: string, files: readonly string[], createId?: () => string): void;

package/dist/gha-selected-files/index.mjs

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+export function encodeSelectedFiles(files) {
+    return files.join('\n');
+}
+// Linux MAX_ARG_STRLEN is 131072. GitHub Actions interpolates selected-file
+// lists into a step env block, so the encoded list plus the variable prefix
+// must fit in one exec argument.
+export const SELECTED_FILES_ENV_MAX_BYTES = 120_000;
+export function selectedFilesExceedEnvBudget(files) {
+    return Buffer.byteLength(encodeSelectedFiles(files), 'utf8') > SELECTED_FILES_ENV_MAX_BYTES;
+}
+export function decodeSelectedFiles(raw) {
+    if (!raw)
+        return [];
+    return raw.split('\n').filter((file) => file.trim().length > 0);
+}
+export function formatMultilineOutput(key, value, createId = randomUUID) {
+    const delimiter = collisionFreeDelimiter(key, value, createId);
+    const body = value === '' ? '' : `${value}\n`;
+    return `${key}<<${delimiter}\n${body}${delimiter}\n`;
+}
+export function writeSelectedFilesOutput(key, files, createId = randomUUID) {
+    const target = process.env.GITHUB_OUTPUT;
+    if (target) {
+        appendFileSync(target, formatMultilineOutput(key, encodeSelectedFiles(files), createId));
+    }
+    console.log(`[select] ${key} (${files.length} file${files.length === 1 ? '' : 's'})`);
+}
+function collisionFreeDelimiter(key, value, createId) {
+    const prefix = key.toUpperCase().replace(/[^A-Z0-9]/g, '_');
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const candidate = `${prefix}_${createId().toUpperCase().replaceAll('-', '_')}`;
+        if (!value.includes(candidate))
+            return candidate;
+    }
+    throw new Error(`could not create a collision-free GitHub output delimiter for ${key} after 10 attempts`);
+}

package/dist/http-origin/index.d.mts

@@ -0,0 +1 @@
+export declare function validateOptionalHttpOrigin(value: string, fieldName?: string): void;

package/dist/http-origin/index.mjs

@@ -0,0 +1,23 @@
+export function validateOptionalHttpOrigin(value, fieldName = 'origin') {
+    if (!value)
+        return;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw invalidOriginError(fieldName);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.pathname !== '/' ||
+        url.search !== '' ||
+        url.hash !== '' ||
+        ![url.origin, `${url.origin}/`].includes(value)) {
+        throw invalidOriginError(fieldName);
+    }
+}
+function invalidOriginError(fieldName) {
+    return new Error(`${fieldName} must be empty or a pure HTTP(S) origin without credentials, path, query, or fragment`);
+}

package/dist/index.d.mts

@@ -9,5 +9,10 @@ export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManif
 export type { InspectedVitestBlobBundle, VitestBlobIdentity, VitestBlobManifest, } from './vitest-blob-manifest/index.mts';
 export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mts';
 export type { InstallOptions, Lifecycle } from './pnpm-install/index.mts';
-export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mts';
-export type { NamedCheck, SharedContext } from './shared-context/index.mts';
+export { buildContextFromTrackedFiles, buildSharedContext, clearFakeGitEnv, gitEnv, installFakeGit, runNamedChecks, setFakeGitTrackedFiles, } from './shared-context/index.mts';
+export type { FakeGitOptions, NamedCheck, SharedContext } from './shared-context/index.mts';
+export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECTED_FILES_ENV_MAX_BYTES, selectedFilesExceedEnvBudget, writeSelectedFilesOutput, } from './gha-selected-files/index.mts';
+export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions, runCleanup, sweepCleanup, } from './gha-artifacts-cleanup/index.mts';
+export type { ArtifactClassification, ArtifactClassifier, ArtifactPatterns, CleanupRequest, DeletionSummary, } from './gha-artifacts-cleanup/index.mts';
+export { validateOptionalHttpOrigin } from './http-origin/index.mts';
+export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/index.mts';

package/dist/index.mjs

@@ -4,4 +4,8 @@ export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, re
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mjs';
 export { createVitestBlobManifest, inspectVitestBlobBundle, parseVitestBlobManifest, serializeVitestBlobManifest, VITEST_BLOB_MANIFEST_FILENAME, VITEST_BLOB_MANIFEST_VERSION, vitestBlobBundlePaths, writeVitestBlobManifest, } from './vitest-blob-manifest/index.mjs';
 export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mjs';
-export { buildContextFromTrackedFiles, buildSharedContext, gitEnv, runNamedChecks, } from './shared-context/index.mjs';
+export { buildContextFromTrackedFiles, buildSharedContext, clearFakeGitEnv, gitEnv, installFakeGit, runNamedChecks, setFakeGitTrackedFiles, } from './shared-context/index.mjs';
+export { decodeSelectedFiles, encodeSelectedFiles, formatMultilineOutput, SELECTED_FILES_ENV_MAX_BYTES, selectedFilesExceedEnvBudget, writeSelectedFilesOutput, } from './gha-selected-files/index.mjs';
+export { createArtifactClassifier, parseArtifactPatternsJson, planRunDeletions, runCleanup, sweepCleanup, } from './gha-artifacts-cleanup/index.mjs';
+export { validateOptionalHttpOrigin } from './http-origin/index.mjs';
+export { boundPendingLine, DEFAULT_MAX_PENDING_LINE_LENGTH, DEFAULT_TRUNCATED_LINE_MARKER, splitCompleteLines, } from './process-line-buffer/index.mjs';

package/dist/pnpm-install/native-health.d.mts

@@ -0,0 +1,4 @@
+export type NativeFamily = 'elf' | 'macho' | 'pe';
+export declare function nativeFamilyFromMagic(buffer: Buffer): NativeFamily | undefined;
+export declare function expectedNativeFamily(platform?: NodeJS.Platform): NativeFamily | undefined;
+export declare function nativeBinariesMatchRuntime(root?: string, platform?: NodeJS.Platform): Promise<boolean>;

package/dist/pnpm-install/native-health.mjs

@@ -0,0 +1,84 @@
+import { glob, open, stat } from 'node:fs/promises';
+import path from 'node:path';
+const ELF = Buffer.from([0x7f, 0x45, 0x4c, 0x46]);
+const PE = Buffer.from([0x4d, 0x5a]);
+const MACHO = [
+    Buffer.from([0xcf, 0xfa, 0xed, 0xfe]),
+    Buffer.from([0xfe, 0xed, 0xfa, 0xcf]),
+    Buffer.from([0xce, 0xfa, 0xed, 0xfe]),
+    Buffer.from([0xfe, 0xed, 0xfa, 0xce]),
+    Buffer.from([0xca, 0xfe, 0xba, 0xbe]),
+    Buffer.from([0xbe, 0xba, 0xfe, 0xca]),
+];
+function startsWith(buffer, magic) {
+    return buffer.length >= magic.length && buffer.subarray(0, magic.length).equals(magic);
+}
+export function nativeFamilyFromMagic(buffer) {
+    if (startsWith(buffer, ELF))
+        return 'elf';
+    if (MACHO.some((magic) => startsWith(buffer, magic)))
+        return 'macho';
+    if (startsWith(buffer, PE))
+        return 'pe';
+    return undefined;
+}
+export function expectedNativeFamily(platform = process.platform) {
+    if (platform === 'linux')
+        return 'elf';
+    if (platform === 'darwin')
+        return 'macho';
+    if (platform === 'win32')
+        return 'pe';
+    return undefined;
+}
+async function readMagic(pathname) {
+    let handle;
+    try {
+        handle = await open(pathname, 'r');
+        const buffer = Buffer.alloc(4);
+        const { bytesRead } = await handle.read(buffer, 0, 4, 0);
+        return bytesRead === 0 ? undefined : buffer.subarray(0, bytesRead);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function searchRoot(nodeModules) {
+    const pnpmStore = path.join(nodeModules, '.pnpm');
+    try {
+        const info = await stat(pnpmStore);
+        return info.isDirectory() ? pnpmStore : nodeModules;
+    }
+    catch {
+        return nodeModules;
+    }
+}
+export async function nativeBinariesMatchRuntime(root = process.cwd(), platform = process.platform) {
+    const expected = expectedNativeFamily(platform);
+    if (expected === undefined)
+        return true;
+    const nodeModules = path.join(root, 'node_modules');
+    try {
+        const info = await stat(nodeModules);
+        if (!info.isDirectory())
+            return true;
+    }
+    catch {
+        return true;
+    }
+    const cwd = await searchRoot(nodeModules);
+    for await (const relative of glob('**/*.{node,bin}', { cwd })) {
+        const magic = await readMagic(path.join(cwd, relative));
+        if (magic === undefined)
+            continue;
+        const family = nativeFamilyFromMagic(magic);
+        if (family !== undefined && family !== expected)
+            return false;
+    }
+    return true;
+}

package/dist/pnpm-install/runner.mjs

@@ -1,5 +1,6 @@
 import { scheduler } from 'node:timers/promises';
 import { persistentDependencyTreeIsCold, persistentMetadataFingerprint, persistentMetadataMatches, writePersistentMetadataStamp, } from './metadata.mjs';
+import { nativeBinariesMatchRuntime } from './native-health.mjs';
 import { runPnpm } from './exec.mjs';
 import { INSTALL_TERMINATION_FAILED } from './process.mjs';
 import { formatReleaseAgeFailure, isReleaseAgeViolation } from './release-age.mjs';
@@ -47,11 +48,15 @@ async function persistent(options) {
     const runCapture = (args) => runPnpm(args, options, true);
     const fingerprint = await persistentMetadataFingerprint(runCapture, options.installScripts);
     const stamped = await persistentMetadataMatches(fingerprint);
+    const nativesMatch = await nativeBinariesMatchRuntime();
+    const provenanceOk = stamped && nativesMatch;
     // An absent tree has nothing to repair, so one ordinary install below matches the
     // reconciled end state. Check first: an install would otherwise make the tree non-cold.
-    const cold = !stamped && (await persistentDependencyTreeIsCold());
-    if (!stamped && !cold) {
-        console.warn('persistent dependency metadata provenance is missing or changed; reconciling');
+    const cold = !provenanceOk && (await persistentDependencyTreeIsCold());
+    if (!provenanceOk && !cold) {
+        console.warn(stamped && !nativesMatch
+            ? 'persistent optional native binaries do not match this runtime; reconciling'
+            : 'persistent dependency metadata provenance is missing or changed; reconciling');
         await reconcileOrFail(options, runCapture);
         await writePersistentMetadataStamp(fingerprint);
         return 'persistent metadata reconciled';

package/dist/process-line-buffer/index.d.mts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_TRUNCATED_LINE_MARKER = " [oversized line truncated] ";
+export declare const DEFAULT_MAX_PENDING_LINE_LENGTH: number;
+export declare function boundPendingLine(value: string, marker?: string, maxLength?: number): string;
+export declare function splitCompleteLines(value: string): {
+    complete: string[];
+    pending: string;
+};

package/dist/process-line-buffer/index.mjs

@@ -0,0 +1,28 @@
+export const DEFAULT_TRUNCATED_LINE_MARKER = ' [oversized line truncated] ';
+export const DEFAULT_MAX_PENDING_LINE_LENGTH = 64 * 1024;
+export function boundPendingLine(value, marker = DEFAULT_TRUNCATED_LINE_MARKER, maxLength = DEFAULT_MAX_PENDING_LINE_LENGTH) {
+    if (value.length <= maxLength)
+        return value;
+    if (marker.length >= maxLength)
+        return marker;
+    const retainedLength = maxLength - marker.length;
+    const headLength = Math.floor(retainedLength / 2);
+    const tailLength = retainedLength - headLength;
+    return value.slice(0, headLength) + marker + value.slice(-tailLength);
+}
+export function splitCompleteLines(value) {
+    const complete = [];
+    let start = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (character !== '\n' && character !== '\r')
+            continue;
+        if (character === '\r' && index === value.length - 1)
+            break;
+        if (character === '\r' && value[index + 1] === '\n')
+            index += 1;
+        complete.push(value.slice(start, index + 1));
+        start = index + 1;
+    }
+    return { complete, pending: value.slice(start) };
+}

package/dist/shared-context/{fake-git.test-helpers.d.mts → fake-git.d.mts}

@@ -8,4 +8,5 @@ export type FakeGitOptions = {
     trackedFiles?: readonly string[];
 };
 export declare function installFakeGit({ binDir, isInsideWorkTree, lsFilesExitCode, lsFilesStderr, pathPrefix, repoRoot, trackedFiles, }: FakeGitOptions): void;
+export declare function setFakeGitTrackedFiles(files: readonly string[]): void;
 export declare function clearFakeGitEnv(): void;

package/dist/shared-context/{fake-git.test-helpers.mjs → fake-git.mjs}

@@ -15,7 +15,10 @@ export function installFakeGit({ binDir, isInsideWorkTree = true, lsFilesExitCod
     process.env[FAKE_GIT_LS_FILES_STDERR] = lsFilesStderr;
     if (repoRoot !== undefined)
         process.env[FAKE_GIT_ROOT] = repoRoot;
-    process.env[FAKE_GIT_FILES] = [...trackedFiles].toSorted().join('\n');
+    setFakeGitTrackedFiles(trackedFiles);
+}
+export function setFakeGitTrackedFiles(files) {
+    process.env[FAKE_GIT_FILES] = [...files].toSorted().join('\n');
 }
 export function clearFakeGitEnv() {
     process.env.FAKE_GIT_INSIDE = 'false';

package/dist/shared-context/index.d.mts

@@ -1,3 +1,5 @@
+export { clearFakeGitEnv, installFakeGit, setFakeGitTrackedFiles } from './fake-git.mts';
+export type { FakeGitOptions } from './fake-git.mts';
 export declare function gitEnv(): NodeJS.ProcessEnv;
 export interface SharedContext {
     repoRoot: string;

package/dist/shared-context/index.mjs

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
+export { clearFakeGitEnv, installFakeGit, setFakeGitTrackedFiles } from './fake-git.mjs';
 export function gitEnv() {
     return Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -65,6 +65,26 @@
       "import": "./dist/shared-context/index.mjs",
       "default": "./dist/shared-context/index.mjs"
     },
+    "./gha-selected-files": {
+      "types": "./dist/gha-selected-files/index.d.mts",
+      "import": "./dist/gha-selected-files/index.mjs",
+      "default": "./dist/gha-selected-files/index.mjs"
+    },
+    "./gha-artifacts-cleanup": {
+      "types": "./dist/gha-artifacts-cleanup/index.d.mts",
+      "import": "./dist/gha-artifacts-cleanup/index.mjs",
+      "default": "./dist/gha-artifacts-cleanup/index.mjs"
+    },
+    "./http-origin": {
+      "types": "./dist/http-origin/index.d.mts",
+      "import": "./dist/http-origin/index.mjs",
+      "default": "./dist/http-origin/index.mjs"
+    },
+    "./process-line-buffer": {
+      "types": "./dist/process-line-buffer/index.d.mts",
+      "import": "./dist/process-line-buffer/index.mjs",
+      "default": "./dist/process-line-buffer/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -75,6 +95,12 @@
     "prepack": "pnpm run build",
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
+  "dependencies": {
+    "picomatch": "4.0.5"
+  },
+  "devDependencies": {
+    "@types/picomatch": "^4.0.3"
+  },
   "optionalDependencies": {
     "@libpg-query/parser": "^18.0.0"
   },

package/scripts/allocate-browser-safe-ports.py

@@ -211,6 +211,7 @@ SCRIPT_NAME = "allocate-browser-safe-ports.py"
 HOLD_POLL_SECONDS = 0.05
 HOLD_READY_TIMEOUT_SECONDS = 2.0
 CONTROL_WAIT_SECONDS = 2.0
+OWNER_PROBE_SECONDS = 0.4
 
 
 def resolve_workspace(workspace: str) -> str:
@@ -560,6 +561,90 @@ def port_is_bindable(port: int) -> bool:
         probe.close()
 
 
+def run_owner_probe(command: list[str]) -> str:
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=OWNER_PROBE_SECONDS,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return result.stdout
+
+
+def compact_probe_text(output: str) -> str:
+    lines = [line.strip() for line in output.splitlines() if line.strip()]
+    return " | ".join(lines)[:200]
+
+
+def pids_holding_port(port: int) -> list[int]:
+    pids: list[int] = []
+    seen: set[int] = set()
+    for raw in run_owner_probe(["lsof", "-nP", "-t", f"-iTCP:{port}"]).split():
+        if not raw.isdigit():
+            continue
+        pid = int(raw)
+        if pid in seen:
+            continue
+        seen.add(pid)
+        pids.append(pid)
+    if pids:
+        return pids
+    for token in run_owner_probe(["ss", "-ntp", f"( sport = :{port} )"]).replace(",", " ").split():
+        if not token.startswith("pid="):
+            continue
+        raw_pid = token[4:].split(")")[0]
+        if not raw_pid.isdigit():
+            continue
+        pid = int(raw_pid)
+        if pid in seen:
+            continue
+        seen.add(pid)
+        pids.append(pid)
+    return pids
+
+
+def sibling_allocator_owner(port: int, excluded_pid: int | None) -> tuple[int, str] | None:
+    for owner_pid in pids_holding_port(port):
+        if excluded_pid is not None and owner_pid == excluded_pid:
+            continue
+        command = process_command_line(owner_pid)
+        if command is None or SCRIPT_NAME not in command:
+            continue
+        return owner_pid, command
+    return None
+
+
+def describe_port_owner(port: int) -> str:
+    pids = pids_holding_port(port)
+    if pids:
+        details: list[str] = []
+        for owner_pid in pids:
+            command = process_command_line(owner_pid) or "unknown"
+            details.append(f"pid {owner_pid} {command}")
+        return compact_probe_text("; ".join(details))
+    lsof_text = compact_probe_text(run_owner_probe(["lsof", "-nP", f"-iTCP:{port}"]))
+    if lsof_text:
+        return f"lsof {lsof_text}"
+    ss_text = compact_probe_text(run_owner_probe(["ss", "-ntp", f"( sport = :{port} )"]))
+    if ss_text:
+        lowered = ss_text.lower()
+        if "time-wait" in lowered or "time_wait" in lowered:
+            return f"TIME_WAIT {ss_text}"
+        return f"ss {ss_text}"
+    return "no owner"
+
+
+def report_sibling_owner(port: int, owner_pid: int, command: str) -> None:
+    print(
+        f"port {port} still held by pid {owner_pid} ({command}); leaving owner in place",
+        file=sys.stderr,
+    )
+
+
 def wait_until_port_bindable(port: int) -> None:
     deadline = time.monotonic() + CONTROL_WAIT_SECONDS
     while time.monotonic() < deadline:
@@ -569,6 +654,29 @@ def wait_until_port_bindable(port: int) -> None:
     raise RuntimeError(f"port {port} did not become bindable")
 
 
+def wait_until_port_bindable_or_sibling(port: int, excluded_pid: int | None) -> None:
+    deadline = time.monotonic() + CONTROL_WAIT_SECONDS
+    probed = False
+    while time.monotonic() < deadline:
+        if port_is_bindable(port):
+            return
+        if not probed:
+            sibling = sibling_allocator_owner(port, excluded_pid)
+            if sibling is not None:
+                report_sibling_owner(port, sibling[0], sibling[1])
+                return
+            probed = True
+        time.sleep(HOLD_POLL_SECONDS)
+    sibling = sibling_allocator_owner(port, excluded_pid)
+    if sibling is not None:
+        report_sibling_owner(port, sibling[0], sibling[1])
+        return
+    occupancy = describe_port_owner(port)
+    raise RuntimeError(
+        f"port {port} did not become bindable after {CONTROL_WAIT_SECONDS}s ({occupancy})"
+    )
+
+
 def request_release(hold_dir: Path, port: int) -> None:
     hold_dir = hold_dir.resolve()
     release_path = hold_dir / "release" / str(port)
@@ -592,9 +700,11 @@ def request_stop(hold_dir: Path, workspace: str) -> None:
     (hold_dir / "stop").write_text("1")
     pid_path = hold_dir / "pid"
     pid = read_pid(pid_path) if pid_path.is_file() else None
+    stopped_live_holder = False
     if pid is not None and pid_is_alive(pid) and is_our_holder(pid, workspace):
         try:
             os.kill(pid, signal.SIGTERM)
+            stopped_live_holder = True
         except ProcessLookupError:
             pass
     deadline = time.monotonic() + CONTROL_WAIT_SECONDS
@@ -607,8 +717,10 @@ def request_stop(hold_dir: Path, workspace: str) -> None:
     if successor is not None and successor != pid:
         # A replacement holder for this workspace already reaped us and took the ports.
         return
+    if not stopped_live_holder:
+        return
     for port in remaining:
-        wait_until_port_bindable(port)
+        wait_until_port_bindable_or_sibling(port, pid)
 
 
 def check_holder(hold_dir: Path, workspace: str) -> None: