Release 3.11.0

.claude/skills/duckdb/SKILL.md

@@ -7,23 +7,22 @@ disable-model-invocation: false
 
 # Query Lite's DuckDB Database
 
-Safely query the PerformanceMonitor Lite DuckDB database using Python. This skill exists because DuckDB only allows one read-write connection at a time. When Lite is running (collecting data), it holds the write connection. External readers MUST connect in read-only mode.
+Safely query the PerformanceMonitor Lite DuckDB database using Python. This skill exists because DuckDB only allows one read-write connection at a time. When Lite is running (collecting data), it holds the write connection, so an external reader connects in read-only mode.
 
 ## Database Location
 
-Since the #1832 fix (data moved OUT of Velopack's install root, which Setup.exe deletes), the store lives at:
+The store lives at:
 ```
 %LOCALAPPDATA%\PerformanceMonitorLite-Data\monitor.duckdb
 ```
-Builds from BEFORE that fix (3.3.0 and earlier) keep it at the old path, and the file only moves when a fixed build first runs:
+Lite 3.3.0 and earlier kept it at the path below, and the file moves to the path above only when a newer build first runs. Check the path above first, and fall back to this one when it does not exist:
 ```
 %LOCALAPPDATA%\PerformanceMonitorLite\monitor.duckdb
 ```
-**Check the -Data path first; fall back to the old path if it does not exist.**
 
-## How to Query (ALWAYS use this pattern)
+## How to Query
 
-Use Python with the `duckdb` module. **ALWAYS connect in read-only mode.**
+Use Python with the `duckdb` module, always with this pattern:
 
 ```python
 python -c "
@@ -40,13 +39,12 @@ con.close()
 "
 ```
 
-## CRITICAL RULES
+## Rules
 
-1. **ALWAYS use `read_only=True`** -- without this, the connection will be blocked by Lite's write lock and hang or fail
-2. **NEVER use `duckdb.connect()` without `read_only=True`** -- the default is read-write which WILL conflict with the running app
-3. **Use forward slashes** in the path (Python on Windows handles this fine)
-4. **Close the connection** when done -- don't leave read locks dangling
-5. **Use Python** -- duckdb 1.4.4 is installed
+1. **Pass `read_only=True` to `duckdb.connect()`.** The default is read-write. Lite's write lock blocks a read-write connection, and it hangs or fails.
+2. **Use forward slashes** in the path (Python on Windows handles this fine)
+3. **Close the connection** when done, so no read lock is left dangling
+4. **Use Python** with its `duckdb` module
 
 ## Common Queries
 

.claude/skills/lane-orders/rig-common.ps1

@@ -0,0 +1,246 @@
+# Shared by rig-start.ps1, rig-stop.ps1 and rig-sweep.ps1 (#5787). Dot-source only.
+#
+# A rig is one throwaway PostgreSQL cluster an agent starts for live test classes:
+#   <RigDir>\pgsql\   the runtime zip, extracted
+#   <RigDir>\data\    the cluster (initdb)
+#   <RigDir>\pg.log   the server log
+# Every rig is registered in one file outside every repo, so a sweep can find the ones whose agent is gone.
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+# One documented location, outside every repo and never committed. Tab-separated, no header, one line per cluster:
+#   data_dir <TAB> pid <TAB> port <TAB> started_utc <TAB> owner
+$script:RigRegistryPath = 'C:\GitHub\worktrees\.rig-registry.tsv'
+
+# The only places a rig data directory may live. Everything else is refused, including a registry line that points
+# elsewhere: the main checkout, Program Files, ProgramData (the Darling service's own managed cluster) and the rest.
+$script:RigAllowedRoots = @(
+    'C:\GitHub\worktrees\',
+    'C:\GitHub\PerformanceMonitor\.claude\worktrees\',
+    'C:\Users\edarl\AppData\Local\Temp\claude\'
+)
+
+# Top-level entries a rig folder holds. A folder with anything else in it keeps those files: only data and pgsql go.
+$script:RigFolderEntries = @('pgsql', 'data', 'pg.log')
+
+function ConvertTo-RigPath {
+    param([Parameter(Mandatory)][string]$Path)
+    $full = [System.IO.Path]::GetFullPath($Path.Replace('/', '\'))
+    return $full.TrimEnd('\')
+}
+
+# Returns $null when the path is an acceptable rig data directory, or the reason it is refused.
+function Get-RigPathRefusal {
+    param([Parameter(Mandatory)][string]$DataDir)
+    $full = ConvertTo-RigPath $DataDir
+    $rigFolder = Split-Path -Parent $full
+    $root = $script:RigAllowedRoots | Where-Object { ($rigFolder + '\').StartsWith($_, [System.StringComparison]::OrdinalIgnoreCase) -and ($rigFolder + '\').Length -gt $_.Length } | Select-Object -First 1
+    if (-not $root) {
+        return "'$full' is not inside a rig folder under an allowed root ($($script:RigAllowedRoots -join ', '))."
+    }
+    if (Test-Path -LiteralPath (Join-Path $rigFolder '.git')) {
+        return "'$rigFolder' holds a .git entry: it is a repo or worktree root, not a rig folder."
+    }
+    foreach ($p in @($rigFolder, $full)) {
+        $item = Get-Item -LiteralPath $p -Force -ErrorAction SilentlyContinue
+        if ($item -and ($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint)) {
+            return "'$p' is a junction or symbolic link."
+        }
+    }
+    return $null
+}
+
+# Reads under the registry lock too: Remove-RigRegistryLine rewrites the whole file, and a reader outside the lock
+# can meet a sharing violation or a half-written file (#5787 review).
+function Read-RigRegistry {
+    $lines = @(Invoke-RigRegistryLocked {
+        if (Test-Path -LiteralPath $script:RigRegistryPath) { Get-Content -LiteralPath $script:RigRegistryPath }
+    })
+    $rows = foreach ($line in $lines) {
+        if ([string]::IsNullOrWhiteSpace($line)) { continue }
+        $f = $line.Split("`t")
+        [pscustomobject]@{
+            DataDir    = $f[0]
+            Pid        = if ($f.Count -gt 1) { $f[1] } else { '' }
+            Port       = if ($f.Count -gt 2) { $f[2] } else { '' }
+            StartedUtc = if ($f.Count -gt 3) { $f[3] } else { '' }
+            Owner      = if ($f.Count -gt 4) { $f[4] } else { '' }
+            Line       = $line
+        }
+    }
+    return @($rows)
+}
+
+# Every registry read and change runs under one machine-wide mutex: lanes start and stop rigs at the same time.
+# A named mutex is owned by its thread, so a holder may nest calls (rig-sweep.ps1 holds it across one rig's
+# decide-and-stop, and Stop-RigCluster takes it again to drop the line). The wait covers one rig's stop (up to
+# about 90 seconds) by another caller.
+function Invoke-RigRegistryLocked {
+    param([Parameter(Mandatory)][scriptblock]$Body)
+    $mutex = [System.Threading.Mutex]::new($false, 'Global\PerformanceMonitorRigRegistry')
+    $held = $false
+    try {
+        try { $held = $mutex.WaitOne([TimeSpan]::FromSeconds(180)) } catch [System.Threading.AbandonedMutexException] { $held = $true }
+        if (-not $held) { throw "Timed out waiting for the rig registry lock." }
+        & $Body
+    }
+    finally {
+        if ($held) { $mutex.ReleaseMutex() }
+        $mutex.Dispose()
+    }
+}
+
+function Add-RigRegistryLine {
+    param([string]$DataDir, [int]$ProcessId, [int]$Port, [string]$Owner)
+    $started = [DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ')
+    $line = ($DataDir, $ProcessId, $Port, $started, ($Owner -replace "[`t`r`n]", ' ')) -join "`t"
+    Invoke-RigRegistryLocked {
+        $dir = Split-Path -Parent $script:RigRegistryPath
+        if (-not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir | Out-Null }
+        Add-Content -LiteralPath $script:RigRegistryPath -Value $line -Encoding utf8NoBOM
+    }
+}
+
+function Remove-RigRegistryLine {
+    param([Parameter(Mandatory)][string]$DataDir)
+    $target = ConvertTo-RigPath $DataDir
+    Invoke-RigRegistryLocked {
+        if (-not (Test-Path -LiteralPath $script:RigRegistryPath)) { return }
+        $keep = @(Get-Content -LiteralPath $script:RigRegistryPath | Where-Object {
+            -not [string]::IsNullOrWhiteSpace($_) -and
+            -not [string]::Equals((ConvertTo-RigPath ($_.Split("`t")[0])), $target, [System.StringComparison]::OrdinalIgnoreCase)
+        })
+        Set-Content -LiteralPath $script:RigRegistryPath -Value $keep -Encoding utf8NoBOM
+    }
+}
+
+# Every running postgres.exe postmaster (no --forkchild), with the data directory its command line names.
+function Get-PostmasterProcesses {
+    $all = @(Get-CimInstance Win32_Process -Filter "Name = 'postgres.exe'")
+    foreach ($p in $all) {
+        $cmd = [string]$p.CommandLine
+        if ($cmd -match '--forkchild') { continue }
+        $data = $null
+        if ($cmd -match '(?:^|\s)-D\s*"([^"]+)"') { $data = $Matches[1] }
+        elseif ($cmd -match '(?:^|\s)-D\s*(\S+)') { $data = $Matches[1] }
+        [pscustomobject]@{
+            ProcessId   = [int]$p.ProcessId
+            DataDir     = if ($data) { ConvertTo-RigPath $data } else { '' }
+            CommandLine = $cmd
+            Children    = @($all | Where-Object { $_.ParentProcessId -eq $p.ProcessId }).Count
+        }
+    }
+}
+
+# True only when the PID is a live postgres.exe postmaster whose command line names this data directory.
+function Test-RigPostmaster {
+    param([int]$ProcessId, [string]$DataDir)
+    $target = ConvertTo-RigPath $DataDir
+    $proc = Get-Process -Id $ProcessId -ErrorAction SilentlyContinue
+    if (-not $proc -or $proc.ProcessName -ne 'postgres') { return $false }
+    $cim = Get-CimInstance Win32_Process -Filter "ProcessId = $ProcessId"
+    if (-not $cim) { return $false }
+    $cmd = ([string]$cim.CommandLine).Replace('/', '\')
+    return $cmd.IndexOf($target, [System.StringComparison]::OrdinalIgnoreCase) -ge 0
+}
+
+# The postmaster PID from <data>\postmaster.pid, or 0.
+function Get-RigPidFilePid {
+    param([string]$DataDir)
+    $pidFile = Join-Path $DataDir 'postmaster.pid'
+    if (-not (Test-Path -LiteralPath $pidFile)) { return 0 }
+    $first = Get-Content -LiteralPath $pidFile -TotalCount 1
+    $n = 0
+    if ([int]::TryParse(([string]$first).Trim(), [ref]$n)) { return $n }
+    return 0
+}
+
+# Stops the cluster in DataDir (pg_ctl first, then the verified postmaster PID), deletes the rig, drops its
+# registry line. Returns an object saying what it did. Refuses any path Get-RigPathRefusal rejects, touching nothing.
+function Stop-RigCluster {
+    param([Parameter(Mandatory)][string]$DataDir, [int]$RegisteredPid = 0)
+    $data = ConvertTo-RigPath $DataDir
+    $refusal = Get-RigPathRefusal $data
+    if ($refusal) {
+        return [pscustomobject]@{ DataDir = $data; Refused = $refusal; Stopped = $false; Deleted = $false; Note = '' }
+    }
+    $rigFolder = Split-Path -Parent $data
+    $result = [pscustomobject]@{ DataDir = $data; Refused = $null; Stopped = $false; Deleted = $false; Note = '' }
+
+    if ((Test-Path -LiteralPath $data) -and -not (Test-Path -LiteralPath (Join-Path $data 'PG_VERSION'))) {
+        $result.Refused = "'$data' exists but holds no PG_VERSION: it is not a PostgreSQL data directory."
+        return $result
+    }
+
+    # The postmaster to stop: postmaster.pid first, the registered PID second; either must prove itself.
+    $postmaster = 0
+    foreach ($candidate in @((Get-RigPidFilePid $data), $RegisteredPid)) {
+        if ($candidate -gt 0 -and (Test-RigPostmaster -ProcessId $candidate -DataDir $data)) { $postmaster = $candidate; break }
+    }
+
+    if ($postmaster -eq 0) {
+        # A live postgres at the postmaster.pid PID that does not name this data directory: deleting under a running
+        # server would tear files out from under it, so keep everything and say so.
+        $filePid = Get-RigPidFilePid $data
+        $proc = if ($filePid -gt 0) { Get-Process -Id $filePid -ErrorAction SilentlyContinue } else { $null }
+        if ($proc -and $proc.ProcessName -eq 'postgres') {
+            $result.Refused = "postmaster.pid names live postgres PID $filePid, whose command line does not name '$data'; nothing touched."
+            return $result
+        }
+    }
+
+    if ($postmaster -gt 0) {
+        $children = @(Get-CimInstance Win32_Process -Filter "ParentProcessId = $postmaster AND Name = 'postgres.exe'" | ForEach-Object { [int]$_.ProcessId })
+        $pgCtl = Join-Path $rigFolder 'pgsql\bin\pg_ctl.exe'
+        if (Test-Path -LiteralPath $pgCtl) {
+            $out = & $pgCtl stop -D $data -m fast -w -t 60 2>&1
+            if ($LASTEXITCODE -ne 0) { $result.Note += "pg_ctl stop exited $LASTEXITCODE ($(($out | Out-String).Trim())); "  }
+        }
+        else {
+            $result.Note += 'pg_ctl.exe missing; stopped the verified postmaster PID; '
+        }
+        if (Get-Process -Id $postmaster -ErrorAction SilentlyContinue) {
+            # Re-verify right before the kill: never stop a PID that is not this cluster's postmaster.
+            if (Test-RigPostmaster -ProcessId $postmaster -DataDir $data) {
+                Stop-Process -Id $postmaster -Force
+            }
+        }
+        # Backends exit on their own once the postmaster is gone; give them time, then stop the stragglers by PID.
+        $deadline = [DateTime]::UtcNow.AddSeconds(20)
+        while ([DateTime]::UtcNow -lt $deadline) {
+            $alive = @($children | Where-Object { Get-Process -Id $_ -ErrorAction SilentlyContinue })
+            if ($alive.Count -eq 0 -and -not (Get-Process -Id $postmaster -ErrorAction SilentlyContinue)) { break }
+            Start-Sleep -Milliseconds 500
+        }
+        foreach ($c in $children) {
+            $proc = Get-Process -Id $c -ErrorAction SilentlyContinue
+            $cim = Get-CimInstance Win32_Process -Filter "ProcessId = $c"
+            if ($proc -and $proc.ProcessName -eq 'postgres' -and $cim -and $cim.ParentProcessId -eq $postmaster) {
+                Stop-Process -Id $c -Force
+            }
+        }
+        if (Get-Process -Id $postmaster -ErrorAction SilentlyContinue) {
+            $result.Note += "postmaster $postmaster still running; folder kept; "
+            return $result
+        }
+        $result.Stopped = $true
+    }
+
+    # Delete: the whole rig folder when it holds only rig entries; otherwise data and pgsql only.
+    if (Test-Path -LiteralPath $rigFolder) {
+        $extra = @(Get-ChildItem -LiteralPath $rigFolder -Force | Where-Object { $script:RigFolderEntries -notcontains $_.Name })
+        $targets = if ($extra.Count -eq 0) { @($rigFolder) } else { @($data, (Join-Path $rigFolder 'pgsql')) | Where-Object { Test-Path -LiteralPath $_ } }
+        if ($extra.Count -gt 0) { $result.Note += "rig folder holds other files ($(($extra.Name | Select-Object -First 3) -join ', ')); removed data and pgsql only; " }
+        foreach ($t in $targets) {
+            for ($attempt = 1; $attempt -le 5; $attempt++) {
+                try { Remove-Item -LiteralPath $t -Recurse -Force; break }
+                catch { if ($attempt -eq 5) { $result.Note += "delete of '$t' failed: $($_.Exception.Message); "; return $result } Start-Sleep -Seconds 2 }
+            }
+        }
+        $result.Deleted = $true
+    }
+
+    Remove-RigRegistryLine $data
+    return $result
+}

.claude/skills/lane-orders/rig-start.ps1

@@ -0,0 +1,88 @@
+<#
+.SYNOPSIS
+  Starts a throwaway PostgreSQL cluster (a rig) for live test classes and registers it (#5787).
+.DESCRIPTION
+  Unpacks the runtime zip into RigDir, runs initdb on RigDir\data with the settings CI's darling-pg job uses plus
+  UTC time zones, starts the server on Port, and appends one line to C:\GitHub\worktrees\.rig-registry.tsv so
+  rig-sweep.ps1 can stop it once its owner is gone. Stop it with rig-stop.ps1 -DataDir <RigDir>\data.
+.EXAMPLE
+  pwsh -NoProfile -File C:\GitHub\PerformanceMonitor\.claude\skills\lane-orders\rig-start.ps1 -Port 55611 `
+    -RigDir C:\Users\edarl\AppData\Local\Temp\claude\<session>\scratchpad\fix-123-thing\rig -Owner C:\GitHub\PerformanceMonitor\.claude\worktrees\agent-x
+#>
+param(
+    [Parameter(Mandatory)][int]$Port,
+    # The rig folder: must not exist yet, or be empty, and must sit under an allowed root (see rig-common.ps1).
+    [Parameter(Mandatory)][string]$RigDir,
+    # The worktree path that uses the rig, or an agent id when there is none. The sweep stops the rig once a
+    # worktree-path owner no longer exists.
+    [Parameter(Mandatory)][string]$Owner,
+    [string]$Zip = 'C:\GitHub\PerformanceMonitor\Darling\artifacts\pg-runtime.zip'
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'rig-common.ps1')
+
+$rig = ConvertTo-RigPath $RigDir
+$data = Join-Path $rig 'data'
+$refusal = Get-RigPathRefusal $data
+if ($refusal) { throw "Refused: $refusal" }
+if ((Test-Path -LiteralPath $rig) -and @(Get-ChildItem -LiteralPath $rig -Force).Count -gt 0) {
+    throw "Refused: '$rig' already exists and is not empty. Pick a new rig folder, or stop the old rig with rig-stop.ps1."
+}
+if (-not (Test-Path -LiteralPath $Zip)) { throw "Runtime zip '$Zip' not found. Run Darling\tools\fetch-pg-runtime.ps1." }
+if (Get-NetTCPConnection -LocalPort $Port -State Listen -ErrorAction SilentlyContinue) { throw "Port $Port is already in use." }
+$taken = @(Read-RigRegistry | Where-Object { $_.Port -eq [string]$Port })
+if ($taken.Count -gt 0) { throw "Port $Port is registered to '$($taken[0].DataDir)' (owner $($taken[0].Owner)). Pick another port, or run rig-sweep.ps1." }
+
+$started = $false
+try {
+    New-Item -ItemType Directory -Force -Path $rig | Out-Null
+    Expand-Archive -LiteralPath $Zip -DestinationPath $rig
+    $bin = Join-Path $rig 'pgsql\bin'
+    if (-not (Test-Path -LiteralPath (Join-Path $bin 'initdb.exe'))) { throw "The zip has no pgsql\bin\initdb.exe." }
+
+    $initOut = & (Join-Path $bin 'initdb.exe') -D $data -U darling -A trust --encoding=UTF8 2>&1
+    if ($LASTEXITCODE -ne 0) { throw "initdb failed ($LASTEXITCODE): $(($initOut | Select-Object -Last 5) -join ' ')" }
+
+    # The darling-pg job's settings in .github/workflows/build.yml, plus UTC: CI's runners run in UTC.
+    Add-Content -LiteralPath (Join-Path $data 'postgresql.conf') -Encoding utf8NoBOM -Value @(
+        "shared_preload_libraries = 'timescaledb,pg_stat_statements'",
+        "port = $Port",
+        "listen_addresses = '127.0.0.1'",
+        "timescaledb.max_background_workers = 74",
+        "max_worker_processes = 85",
+        "log_line_prefix = '%m [%p] %c '",
+        "timezone = 'UTC'",
+        "log_timezone = 'UTC'"
+    )
+
+    # The postmaster inherits every inheritable handle of the process that starts it, including the caller's
+    # stdout pipe, so a plain `pg_ctl -w start` (or Start-Process with redirection, which inherits too) holds a
+    # tool call open until the server stops. Start-Process without -NoNewWindow or redirection goes through
+    # ShellExecute in a hidden window, which passes no handles; pg.log carries everything pg_ctl would print.
+    $log = Join-Path $rig 'pg.log'
+    $pgCtl = Start-Process -FilePath (Join-Path $bin 'pg_ctl.exe') -PassThru -WindowStyle Hidden `
+        -ArgumentList @('start', '-D', "`"$data`"", '-o', "`"-p $Port`"", '-w', '-t', '90', '-l', "`"$log`"")
+    $null = $pgCtl.Handle
+    if (-not $pgCtl.WaitForExit(120000)) { throw "pg_ctl start did not return in 120 seconds." }
+    $started = $true
+    if ($pgCtl.ExitCode -ne 0) { throw "pg_ctl start failed ($($pgCtl.ExitCode)): $((Get-Content -LiteralPath $log -Tail 10 -ErrorAction SilentlyContinue) -join ' ')" }
+    if (-not (Select-String -LiteralPath $log -Pattern 'ready to accept connections' -Quiet)) { throw "The log at '$log' never said 'ready to accept connections'." }
+
+    $postmaster = Get-RigPidFilePid $data
+    if (-not (Test-RigPostmaster -ProcessId $postmaster -DataDir $data)) { throw "postmaster.pid PID $postmaster is not this cluster's postmaster." }
+
+    Add-RigRegistryLine -DataDir $data -ProcessId $postmaster -Port $Port -Owner $Owner
+    Write-Host "Rig started: data $data, PID $postmaster, port $Port, owner $Owner. Registered in $script:RigRegistryPath."
+    Write-Host "Stop it with: pwsh -NoProfile -File $(Join-Path $PSScriptRoot 'rig-stop.ps1') -DataDir $data"
+}
+catch {
+    # Leave nothing behind that no registry line points at.
+    $failure = $_
+    if ($started -or (Test-Path -LiteralPath $rig)) {
+        $cleanup = Stop-RigCluster -DataDir $data
+        if ($cleanup.Refused -or $cleanup.Note) { Write-Warning "Cleanup after the failed start: $($cleanup.Refused) $($cleanup.Note)" }
+    }
+    throw $failure
+}