From af505f9299ade5f7eb831262ac485a28e8d6cb1e Mon Sep 17 00:00:00 2001
From: Dimitri Furman <dfurman@microsoft.com>
Date: Tue, 14 Jul 2026 19:54:50 -0400
Subject: [PATCH 1/2] Add ShrinkDriver sample: parallel DBCC SHRINKFILE with
 reporting, retries, and tests

A PowerShell sample that reclaims unused space from a database's data files by running parallel DBCC SHRINKFILE operations. Includes a report mode, incremental shrinking toward an optional target, progress monitoring, retries, graceful stop handling, and low-priority locking. Supports Entra ID, Windows, and SQL authentication, connects with certificate validation first, and ships unit and integration tests (LocalDB, SQL Server, and Azure SQL Database).
---
 .../features/shrink/shrink-driver/.gitignore  |    2 +
 .../features/shrink/shrink-driver/README.md   |  151 ++
 .../shrink/shrink-driver/src/ShrinkDriver.ps1 | 1614 +++++++++++++++++
 .../shrink/shrink-driver/tests/README.md      |  101 ++
 .../tests/ShrinkDriver.Integration.Tests.ps1  |  339 ++++
 .../tests/ShrinkDriver.Unit.Tests.ps1         |  507 ++++++
 .../tests/fixtures/ShrinkTestDb.psm1          |  333 ++++
 7 files changed, 3047 insertions(+)
 create mode 100644 samples/features/shrink/shrink-driver/.gitignore
 create mode 100644 samples/features/shrink/shrink-driver/README.md
 create mode 100644 samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1
 create mode 100644 samples/features/shrink/shrink-driver/tests/README.md
 create mode 100644 samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1
 create mode 100644 samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1
 create mode 100644 samples/features/shrink/shrink-driver/tests/fixtures/ShrinkTestDb.psm1

diff --git a/samples/features/shrink/shrink-driver/.gitignore b/samples/features/shrink/shrink-driver/.gitignore
new file mode 100644
index 0000000000..e4a1d65eab
--- /dev/null
+++ b/samples/features/shrink/shrink-driver/.gitignore
@@ -0,0 +1,2 @@
+# Run logs produced by Invoke-ShrinkDriver
+*.log
diff --git a/samples/features/shrink/shrink-driver/README.md b/samples/features/shrink/shrink-driver/README.md
new file mode 100644
index 0000000000..982bd25c2b
--- /dev/null
+++ b/samples/features/shrink/shrink-driver/README.md
@@ -0,0 +1,151 @@
+# ShrinkDriver
+
+Reclaim allocated but unused space from the data files of a MSSQL database
+by running parallel `DBCC SHRINKFILE` operations, with progress monitoring,
+incremental shrinking, and automatic retries.
+
+## What it does
+
+- Runs in two modes: `Report` (default) shows each file's used, allocated, and reclaimable space without changing anything; `Shrink` performs the shrink.
+- Shrinks multiple data files at once (one session per file) to reduce total run time.
+- Shrinks each file gradually in incremental steps toward an optional target size, instead of in one large operation.
+- Retries transient failures with backoff, and moves on from files that cannot shrink further.
+- Skips files with little unused space to reclaim.
+- Optionally runs shrink at low lock priority to reduce blocking of other queries.
+- Writes a status report to the console and a log file at a regular interval, and stops on Ctrl+C or an optional time limit.
+- Supports Entra ID, Windows, and SQL authentication when connecting to the database.
+
+## Requirements
+
+- SQL Server 2022 or later, Azure SQL Managed Instance, or Azure SQL Database.
+- To shrink (`-Mode Shrink`): membership in the `db_owner` database role, or the `sysadmin` server role.
+- To report (`-Mode Report`, the default): connection to the database.
+- PowerShell 7 or later.
+- The `SqlServer` module:
+  `Install-Module SqlServer -Scope CurrentUser`.
+
+## Usage
+
+Load the script, then call `Invoke-ShrinkDriver`:
+
+```powershell
+. .\src\ShrinkDriver.ps1
+
+# Report (default): show each file's used, allocated, and reclaimable space, without changing anything
+Invoke-ShrinkDriver -ServerName myserver.database.windows.net -DatabaseName MyDb
+
+# Shrink with Entra ID auth (default) to the smallest possible size, working on up to 5 files concurrently
+Invoke-ShrinkDriver -ServerName myserver.database.windows.net -DatabaseName MyDb -Mode Shrink -Sessions 5
+
+# Shrink with Windows auth: don't shrink below 500 GiB, working on up to 8 files concurrently
+Invoke-ShrinkDriver -ServerName sql01 -DatabaseName MyDb -Mode Shrink -AuthType Windows -FileTargetSizeGiB 500 -Sessions 8
+
+# Shrink with SQL auth (prompts securely for the password when it is not supplied)
+Invoke-ShrinkDriver -ServerName sql01 -DatabaseName MyDb -Mode Shrink -AuthType SQL -SqlLogin appuser
+
+# Connect to an instance with a self-signed certificate
+Invoke-ShrinkDriver -ServerName devsql01 -DatabaseName MyDb -Mode Shrink -AuthType Windows -TrustServerCertificate
+```
+
+For the full list of parameters and what they do:
+
+```powershell
+Get-Help Invoke-ShrinkDriver -Full
+```
+
+## Output
+
+Progress is written to the console and mirrored to a log file — by default a
+timestamped `shrink-<time>.log` next to the script, or the
+path given with `-LogPath`. The log records specified parameter values and a 
+periodic per-file status report plus notable events (retries and cancellations).
+
+### Status report
+
+Each periodic report has one row per worker session, with these columns:
+
+- **Worker** — the worker number.
+- **SPID** — its session ID on the server.
+- **File** — the data file being shrunk.
+- **Used**, **Alloc** — the file's used and allocated size.
+- **%Done** — progress of the current `DBCC SHRINKFILE` increment as reported in `sys.dm_exec_requests`.
+- **Elapsed** — time since the worker's session was established.
+- **Increment** — the number of the current incremental shrink step.
+- **Cmd** — the current shrink phase, as reported by `sys.dm_exec_requests`, such as `DbccSpaceReclaim` or `DbccFilesCompact`.
+- **Status** — the request's execution status (running, suspended, and so on).
+- **dCPU**, **dReads**, **dWrites** — CPU, reads, and writes since the previous report, within the same shrink increment.
+- **Blocker** — the blocking session, if any.
+- **Wait** — the current wait type, if any.
+
+It closes with a database-wide total: overall run time, total used and allocated
+space, and a running tally of file outcomes.
+
+Here's an example of the status report:
+
+```output
+2026-07-13 11:30:04 [INFO] ---- status ----
+2026-07-13 11:30:04 [INFO] Worker  SPID  File  Used (GiB)  Alloc (GiB)  %Done     Elapsed  Increment  Cmd               Status       dCPU  dReads  dWrites  Blocker                 Wait              
+2026-07-13 11:30:04 [INFO] ------  ----  ----  ----------  -----------  -----  ----------  ---------  ----------------  ---------  ------  ------  -------  ----------------------  ------------------
+2026-07-13 11:30:04 [INFO]      0   157    13        66.3         78.0   88.8  4h 37m 34s         12  DbccFilesCompact  suspended  37,507  68,713  143,163  -                       PAGEIOLATCH_EX 1ms
+2026-07-13 11:30:04 [INFO]      1   160    11        66.2         78.0     89  4h 37m 34s         13  DbccFilesCompact  suspended  34,064  69,614  143,715  -                       PAGEIOLATCH_EX 1ms
+2026-07-13 11:30:04 [INFO]      2   162    33        43.5         50.0   89.6  4h 37m 33s         17  DbccFilesCompact  runnable   45,499  67,346  141,368  -                                         
+2026-07-13 11:30:04 [INFO]      3   143    12        65.7         68.0   97.2  4h 37m 34s         18  DbccFilesCompact  suspended       -       -        -  -                       PAGEIOLATCH_EX 0ms
+2026-07-13 11:30:04 [INFO]      4   170    31        80.2         88.0   93.7  4h 37m 34s         11  DbccFilesCompact  running    45,815  66,481  154,862  -                                         
+2026-07-13 11:30:04 [INFO]      5   179     6        70.3         78.4   92.5  4h 37m 33s         12  DbccFilesCompact  suspended  33,075  79,371  153,667  164 (DbccFilesCompact)  LCK_M_X 0ms       
+2026-07-13 11:30:04 [INFO]      6   164     5        72.4         98.0   92.3  4h 37m 34s         15  DbccFilesCompact  running    45,118  79,988  175,718  -                                         
+2026-07-13 11:30:04 [INFO]      7   172    29        80.5         98.0   94.6  4h 37m 33s         11  DbccFilesCompact  running    36,587  69,368  143,467  -                                         
+2026-07-13 11:30:04 [INFO]      8   161    34        31.4         50.0   92.5  4h 37m 34s         14  DbccFilesCompact  suspended  39,537  55,254  150,108  179 (DbccFilesCompact)  LCK_M_X 5ms       
+2026-07-13 11:30:04 [INFO]      9   141    30        80.4         88.0   92.6  4h 37m 34s         12  DbccFilesCompact  suspended  40,900  68,313  150,113  161 (DbccFilesCompact)  LCK_M_X 2ms       
+2026-07-13 11:30:04 [INFO] ---- database total ----
+2026-07-13 11:30:04 [INFO]   Run time           : 12h 10m 24s
+2026-07-13 11:30:04 [INFO]   Used               : 2.3 TiB
+2026-07-13 11:30:04 [INFO]   Allocated          : 2.5 TiB
+2026-07-13 11:30:04 [INFO]   Shrunk             : 16
+2026-07-13 11:30:04 [INFO]   Repacked           : 0
+2026-07-13 11:30:04 [INFO]   Partly shrunk      : 1
+2026-07-13 11:30:04 [INFO]   Already at minimum : 0
+2026-07-13 11:30:04 [INFO]   Already at target  : 0
+2026-07-13 11:30:04 [INFO]   Grew               : 0
+2026-07-13 11:30:04 [INFO]   Gave up            : 0
+```
+
+### End summary
+
+A summary at the end reports how each file ended up:
+
+- **Shrunk** — the file was reduced in size, reaching the target or minimum size.
+- **Repacked** — with `-NoTruncate`, data pages were moved toward the front of the file; the allocated size is unchanged by design (space is not released).
+- **Partly shrunk** — reduced, but gave up before reaching the target or minimum size.
+- **Already at minimum** — already at its smallest possible size; nothing to reclaim.
+- **Already at target** — already at or below the requested target size.
+- **Grew** — ended larger than it started because other sessions added data during the shrink.
+- **Gave up** — abandoned after retries with no change in size.
+- **Interrupted** — shrinking of this file was cut short before any measurable result.
+- **Not processed** — eligible for shrinking, but the run ended before it was completed (for example, it never started, or the connection was lost and could not be recovered).
+
+Here's an example of the end summary:
+
+```output
+2026-07-13 12:31:24 [INFO] -------------------- summary --------------------
+2026-07-13 12:31:24 [INFO]   Run time           : 13h 11m 44s
+2026-07-13 12:31:24 [INFO]   Used               : 2.3 TiB
+2026-07-13 12:31:24 [INFO]   Allocated          : 2.3 TiB
+2026-07-13 12:31:24 [INFO]   Shrunk             : 30
+2026-07-13 12:31:24 [INFO]   Repacked           : 0
+2026-07-13 12:31:24 [INFO]   Partly shrunk      : 1
+2026-07-13 12:31:24 [INFO]   Already at minimum : 0
+2026-07-13 12:31:24 [INFO]   Already at target  : 0
+2026-07-13 12:31:24 [INFO]   Grew               : 0
+2026-07-13 12:31:24 [INFO]   Gave up            : 0
+2026-07-13 12:31:24 [INFO]   file 35 [PartlyShrunk]: reduced from 40.0 GiB to 10.0 GiB, but the remaining unused space could not be reclaimed
+2026-07-13 12:31:24 [INFO] -------------------------------------------------
+```
+
+## Tests
+
+The script ships with unit and integration tests. For more information, see [tests/README.md](tests/README.md).
+
+## Shrink documentation
+
+- [DBCC SHRINKFILE](https://learn.microsoft.com/sql/t-sql/database-console-commands/dbcc-shrinkfile-transact-sql).
+- [Manage file space for databases in Azure SQL Database](https://learn.microsoft.com/azure/azure-sql/database/file-space-manage).
diff --git a/samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1 b/samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1
new file mode 100644
index 0000000000..1c4ff83608
--- /dev/null
+++ b/samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1
@@ -0,0 +1,1614 @@
+#Requires -Version 7.0
+<#
+.SYNOPSIS
+  Loads Invoke-ShrinkDriver, a command that reclaims allocated but unused space from
+  a MSSQL database's data files by running DBCC SHRINKFILE commands in parallel on
+  multiple sessions.
+
+.DESCRIPTION
+  Dot-source this file to define the command, then call it:
+
+    . .\ShrinkDriver.ps1
+    Invoke-ShrinkDriver -ServerName <server> -DatabaseName <database>
+
+  Requires PowerShell 7 or later. Depends on the SqlServer module
+  (Install-Module SqlServer -Scope CurrentUser). See the README for the full list.
+
+  Run 'Get-Help Invoke-ShrinkDriver -Full' for the description, parameters, and examples.
+#>
+
+Set-StrictMode -Version Latest
+
+function Invoke-ShrinkDriver {
+    <#
+    .SYNOPSIS
+      Reclaims unused space from a database's data files by running several
+      DBCC SHRINKFILE operations in parallel, with progress monitoring and retries.
+    .DESCRIPTION
+      Connects to the target database, shrinks each eligible data file toward the
+      requested size in steps using multiple concurrent sessions, and writes a status
+      report to the console and a log file at a regular interval.
+
+      Requires PowerShell 7 or later and membership in the db_owner database role
+      or the sysadmin server role. Supported platforms: SQL Server 2022 or later,
+      Azure SQL Managed Instance, and Azure SQL Database.
+
+      Entra ID authentication first uses the ambient Azure credential (managed identity,
+      Azure CLI, Azure PowerShell, or Visual Studio); if none is available it falls back
+      to an interactive browser sign-in. To use a specific account, sign in first (for
+      example, Connect-AzAccount or az login).
+
+      Dependencies: the SqlServer module.
+    .PARAMETER ServerName
+      Target SQL Server / Azure SQL logical server name.
+    .PARAMETER DatabaseName
+      Target database name.
+    .PARAMETER AuthType
+      Authentication method: EntraID (default), Windows, or SQL.
+    .PARAMETER SqlLogin
+      Login name; required when AuthType is SQL.
+    .PARAMETER SqlPassword
+      Password as a SecureString, used when AuthType is SQL. Optional: if omitted, you are prompted for
+      it securely at run time. If supplied it must be a SecureString, not plain text - for example:
+      $pw = Read-Host -AsSecureString 'SQL password'. A plain string is rejected.
+    .PARAMETER TrustServerCertificate
+      Allow connecting when the server's TLS certificate cannot be validated - for example a local
+      development SQL Server with a self-signed certificate (the connection is still encrypted). Off by
+      default. It is a fallback only: the driver always tries a fully validated connection first, so a
+      server with a trusted certificate (such as Azure SQL) is never connected to without validation.
+    .PARAMETER Sessions
+      The maximum number of files to shrink concurrently (default 5). Capped at the eligible file count.
+    .PARAMETER TruncateOnly
+      Release unused space at the end of each file only, without moving data.
+    .PARAMETER NoTruncate
+      Compact each file without releasing the unused space.
+    .PARAMETER Mode
+      Report (default) lists each data file's used, allocated, and potentially reclaimable space,
+      plus a database-wide summary, without changing anything; Shrink performs the DBCC SHRINKFILE
+      operations. Report respects -FileTargetSizeGiB (reclaimable is measured down to the target,
+      otherwise down to the used space) and ignores the other shrink options. For databases with
+      more than 100 data files, only the 100 most reclaimable files are listed, with a note of how
+      many were omitted.
+    .PARAMETER WaitAtLowPriority
+      Run shrink at low lock priority to reduce blocking of other queries (default true).
+    .PARAMETER AbortAfterWait
+      On a low-priority wait timeout, abort file shrink (SELF, default) or kill the
+      blocking sessions (BLOCKERS). BLOCKERS terminates other transactions, use with caution.
+    .PARAMETER FileTargetSizeGiB
+      Optional per-file floor in GiB; no file is shrunk below this size.
+    .PARAMETER RetryCount
+      Retry attempts per file for transient failures (default 5, range 0-50; 0 disables retries).
+    .PARAMETER MaxRuntimeMinutes
+      Optional overall time budget; the run stops when it is reached.
+    .PARAMETER StepGiB
+      Increment size used for gradual shrinking (default 20 GiB).
+    .PARAMETER MinReclaimGiB
+      Minimum unused space per file, in GiB, worth running a shrink pass to reclaim. A file whose unused space -
+      or a file's remaining unused space after earlier passes - is below this is left as is (default 1 GiB).
+    .PARAMETER StatusIntervalSeconds
+      How often the status report is written, in seconds (default 180).
+    .PARAMETER StuckWindowSeconds
+      A shrink blocked with no progress for this long is cancelled and retried (default 300).
+      Stuck detection runs only at each status report, so this is effectively rounded up to a
+      multiple of StatusIntervalSeconds; a value below StatusIntervalSeconds is raised to it.
+    .PARAMETER LogPath
+      Log file path. Defaults to a timestamped file next to this script. The parent directory
+      must already exist and be writable; otherwise the run stops before doing any work.
+    .PARAMETER PassThru
+      Emit a structured result object (mode, totals, per-file outcomes) to the pipeline for
+      programmatic callers. By default the run reports only to the console and log and returns
+      nothing, so interactive runs are not cluttered with a raw object dump.
+    .EXAMPLE
+      Invoke-ShrinkDriver -ServerName myserver.database.windows.net -DatabaseName MyDb -Sessions 5
+    .EXAMPLE
+      Invoke-ShrinkDriver -ServerName sql01 -DatabaseName MyDb -AuthType Windows -FileTargetSizeGiB 500 -Sessions 8
+    .LINK
+      https://learn.microsoft.com/azure/azure-sql/database/file-space-manage
+    .LINK
+      https://learn.microsoft.com/sql/t-sql/database-console-commands/dbcc-shrinkfile-transact-sql
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$ServerName,
+        [Parameter(Mandatory)][string]$DatabaseName,
+
+        [ValidateSet('EntraID', 'Windows', 'SQL')][string]$AuthType = 'EntraID',
+        [string]$SqlLogin,
+        [object]$SqlPassword,
+        [switch]$TrustServerCertificate,
+
+        [ValidateRange(1, [int]::MaxValue)][int]$Sessions = 5,
+        [ValidateSet('Report', 'Shrink')][string]$Mode = 'Report',
+        [switch]$TruncateOnly,
+        [switch]$NoTruncate,
+        [bool]$WaitAtLowPriority = $true,
+        [ValidateSet('SELF', 'BLOCKERS')][string]$AbortAfterWait = 'SELF',
+
+        [ValidateRange(0, [int]::MaxValue)][Nullable[int]]$FileTargetSizeGiB = $null,
+        [ValidateRange(0, 50)][int]$RetryCount = 5,
+        [ValidateRange(1, [int]::MaxValue)][Nullable[int]]$MaxRuntimeMinutes = $null,
+
+        [ValidateRange(1, [int]::MaxValue)][int]$StepGiB = 20,
+        [ValidateRange(0, [int]::MaxValue)][int]$MinReclaimGiB = 1,
+        [ValidateRange(1, [int]::MaxValue)][int]$StatusIntervalSeconds = 180,
+        [ValidateRange(1, [int]::MaxValue)][int]$StuckWindowSeconds = 300,
+        [string]$LogPath,
+        [switch]$PassThru,
+
+        # --- Test-only parameters (intentionally omitted from help; not for normal use) ---
+        # Shorten retry backoff and allow sub-GiB sizes / a seconds-level time limit so integration
+        # tests can drive the real paths quickly and deterministically.
+        [int]$BackoffBaseSeconds = 5,
+        [int]$BackoffCapSeconds = 60,
+        [Nullable[long]]$StepMBOverride = $null,
+        [Nullable[long]]$MinReclaimMBOverride = $null,
+        [Nullable[long]]$FileTargetMBOverride = $null,
+        [Nullable[int]]$MaxRuntimeSecondsOverride = $null
+    )
+
+    $ErrorActionPreference = 'Stop'
+    $selfPath = $PSCommandPath
+    $hasTarget = ($null -ne $FileTargetSizeGiB) -or ($null -ne $FileTargetMBOverride)
+
+    # ----- validate parameters -----
+    $paramSet = @{
+        AuthType = $AuthType; SqlLogin = $SqlLogin; SqlPassword = $SqlPassword
+        TruncateOnly = [bool]$TruncateOnly; NoTruncate = [bool]$NoTruncate
+        WaitAtLowPriority = $WaitAtLowPriority; AbortAfterWait = $AbortAfterWait
+        FileTargetSizeGiB = $(if ($hasTarget) { [int]$FileTargetSizeGiB } else { $null })
+    }
+    $validationErrors = Test-ShrinkParameterSet -Params $paramSet
+    if ($validationErrors.Count -gt 0) {
+        $validationErrors | ForEach-Object { Write-Error $_ }
+        throw "Parameter validation failed with $($validationErrors.Count) error(s)."
+    }
+    # SQL auth: prompt for the password securely if it was not supplied, so it never has to be typed on
+    # the command line (where it would be visible and saved in history). Validation already confirmed a
+    # SecureString when one was passed, and that SqlLogin is present.
+    if ($AuthType -eq 'SQL' -and -not $SqlPassword) {
+        $SqlPassword = Read-Host -AsSecureString "SQL password for login '$SqlLogin'"
+    }
+    $stepMB = if ($null -ne $StepMBOverride) { [long]$StepMBOverride } else { [long]$StepGiB * 1024 }
+    $floorMB = if ($null -ne $FileTargetMBOverride) { [long]$FileTargetMBOverride } elseif ($null -ne $FileTargetSizeGiB) { [long]$FileTargetSizeGiB * 1024 } else { $null }
+    $minReclaimMB = if ($null -ne $MinReclaimMBOverride) { [long]$MinReclaimMBOverride } else { [long]$MinReclaimGiB * 1024 }
+
+    # ----- logging (console + mirrored file) -----
+    if (-not $LogPath) {
+        $stamp = (Get-Date).ToString('yyyyMMdd-HHmmss')
+        $LogPath = Join-Path $PSScriptRoot ("shrink-{0}.log" -f $stamp)
+    }
+    # Validate up front so a bad path fails fast with a clear message instead of failing
+    # part-way through the run; also normalizes to a full path for the logged 'LogFile' value.
+    $LogPath = Resolve-ShrinkLogPath -Path $LogPath
+    $logLock = [object]::new()
+    # Console color is additive emphasis only (the level tag and text convey everything without it);
+    # the log file always gets plain text. Honor the NO_COLOR convention to turn it off.
+    $useColor = [string]::IsNullOrEmpty($env:NO_COLOR)
+    function Write-ShrinkLog {
+        param([string]$Message, [string]$Level = 'INFO')
+        $stamp = (Get-Date).ToString('yyyy-MM-dd HH:mm:ss')
+        $line = '{0} [{1}] {2}' -f $stamp, $Level, $Message
+        [System.Threading.Monitor]::Enter($logLock)
+        try {
+            Add-Content -LiteralPath $LogPath -Value $line -Encoding utf8
+            if (-not $useColor) {
+                Write-Host $line
+            }
+            else {
+                $tagColor = switch ($Level) { 'ERROR' { 'Red' } 'WARN' { 'Yellow' } 'EVENT' { 'DarkCyan' } default { 'DarkGray' } }
+                $msgColor = switch ($Level) {
+                    'ERROR' { 'Red' }
+                    'WARN' { 'Yellow' }
+                    default {
+                        if ($Message -match '^-{3,}') { 'Cyan' }                                          # section dividers/headers
+                        elseif ($Message -match '(Grew|Gave up|Partly shrunk)\s*:\s*[1-9]') { 'Yellow' }  # non-zero problem outcomes
+                        elseif ($Message -match '(Shrunk|Repacked)\s*:\s*[1-9]') { 'Green' }               # non-zero successful outcomes
+                        else { $null }
+                    }
+                }
+                Write-Host $stamp -ForegroundColor DarkGray -NoNewline
+                Write-Host (' [{0}] ' -f $Level) -ForegroundColor $tagColor -NoNewline
+                if ($null -ne $msgColor) { Write-Host $Message -ForegroundColor $msgColor }
+                else { Write-Host $Message }
+            }
+        }
+        finally { [System.Threading.Monitor]::Exit($logLock) }
+    }
+
+    @(
+        '-------------------- ShrinkDriver run --------------------'
+        "Server           : $ServerName"
+        "Database         : $DatabaseName"
+        "Mode             : $Mode"
+        "AuthType         : $AuthType" + $(if ($AuthType -eq 'SQL') { " (login $SqlLogin)" } else { '' })
+        "TrustServerCert  : $([bool]$TrustServerCertificate)" + $(if ([bool]$TrustServerCertificate) { ' (used only as a fallback if certificate validation fails)' } else { '' })
+        "Sessions         : $Sessions"
+        "TruncateOnly     : $([bool]$TruncateOnly)"
+        "NoTruncate       : $([bool]$NoTruncate)"
+        "WaitAtLowPriority: $WaitAtLowPriority"
+        "AbortAfterWait   : $AbortAfterWait"
+        "FileTargetSizeGiB: $(if ($hasTarget) { [int]$FileTargetSizeGiB } else { '(min possible)' })"
+        "StepGiB          : $StepGiB"
+        "MinReclaimGiB    : $MinReclaimGiB"
+        "RetryCount       : $RetryCount"
+        "MaxRuntimeMinutes: $(if ($null -ne $MaxRuntimeMinutes) { [int]$MaxRuntimeMinutes } else { '(none)' })"
+        "StatusInterval   : $StatusIntervalSeconds s"
+        "LogFile          : $LogPath"
+        '----------------------------------------------------------'
+    ) | ForEach-Object { Write-ShrinkLog $_ }
+    if ($WaitAtLowPriority -and $AbortAfterWait -eq 'BLOCKERS') {
+        Write-ShrinkLog 'AbortAfterWait=BLOCKERS will roll back transactions that block shrink. Use with caution.' 'WARN'
+    }
+    # Stuck detection only runs at each status report, so a stuck window finer than the report
+    # cadence cannot be honored. Raise it to the report interval and tell the user.
+    if ($StuckWindowSeconds -lt $StatusIntervalSeconds) {
+        Write-ShrinkLog ("StuckWindowSeconds ({0}s) is below StatusIntervalSeconds ({1}s); stuck detection only runs at each status report, so raising StuckWindowSeconds to {1}s." -f $StuckWindowSeconds, $StatusIntervalSeconds) 'WARN'
+        $StuckWindowSeconds = $StatusIntervalSeconds
+    }
+
+    # Log any terminating error to the file before it propagates to the console.
+    $control = $null
+    $runResult = $null
+    try {
+
+    # ----- connection helpers -----
+    # The Microsoft.Data.SqlClient types come from the SqlServer module. Import it on
+    # demand; if it is not installed, stop with instructions to install it.
+    if (-not ('Microsoft.Data.SqlClient.SqlConnection' -as [type])) {
+        if (-not (Get-Module -ListAvailable -Name SqlServer)) {
+            throw "The 'SqlServer' module is required but not installed. Install it with " +
+                  "'Install-Module SqlServer -Scope CurrentUser' (needs PowerShell 7 or later), then retry."
+        }
+        Import-Module SqlServer -ErrorAction Stop
+    }
+    function New-ShrinkConnection {
+        $csb = [Microsoft.Data.SqlClient.SqlConnectionStringBuilder]::new()
+        $csb['Data Source'] = $ServerName; $csb['Initial Catalog'] = $DatabaseName
+        $csb['Encrypt'] = $true; $csb['Connect Timeout'] = 30; $csb['Application Name'] = 'ShrinkDriver'
+        # This tool holds a few long-lived connections, so pooling gives no benefit and would keep the
+        # physical connection (and its server session) open after Dispose, to be handed back to a later
+        # run. Turn pooling off so Close/Dispose actually closes the connection when we are done.
+        $csb['Pooling'] = $false
+        # A connection-level retry provider rides out transient open failures (for example an Azure
+        # SQL restart or failover). It is a shallow inner retry; callers keep their own retry loop.
+        $retry = New-ShrinkRetryProvider
+        if ($AuthType -eq 'Windows') {
+            $csb['Integrated Security'] = $true
+            $conn = Open-ShrinkSqlConnection -Builder $csb -RetryProvider $retry -AllowTrustServerCertificate ([bool]$TrustServerCertificate)
+            return [pscustomobject]@{ Connection = $conn; EntraMode = $null }
+        }
+        if ($AuthType -eq 'SQL') {
+            $pw = $SqlPassword.Copy(); $pw.MakeReadOnly()
+            $cred = [Microsoft.Data.SqlClient.SqlCredential]::new($SqlLogin, $pw)
+            $conn = Open-ShrinkSqlConnection -Builder $csb -Credential $cred -RetryProvider $retry -AllowTrustServerCertificate ([bool]$TrustServerCertificate)
+            return [pscustomobject]@{ Connection = $conn; EntraMode = $null }
+        }
+        # EntraID: try the ambient credential (managed identity, Azure CLI, Azure PowerShell,
+        # Visual Studio) first; if it is unavailable, fall back to interactive sign-in. The mode
+        # that succeeds is reused by the worker sessions. EntraID targets Azure SQL, whose certificate
+        # is always valid, so certificate trust is never needed here.
+        foreach ($mode in @('Active Directory Default', 'Active Directory Interactive')) {
+            $csb['Authentication'] = $mode
+            try {
+                $conn = Open-ShrinkSqlConnection -Builder $csb -RetryProvider $retry -AllowTrustServerCertificate $false
+                return [pscustomobject]@{ Connection = $conn; EntraMode = $mode }
+            } catch {
+                if ($mode -eq 'Active Directory Interactive') { throw }
+                # The ambient credential is often unavailable on dev machines, and interactive
+                # sign-in silently reuses a cached token (no browser prompt) when one exists, so
+                # this fallback is not worth a warning on every run. Surface it only under -Verbose.
+                Write-Verbose ("Ambient Azure sign-in unavailable ({0}); falling back to interactive sign-in." -f $_.Exception.Message.Split([Environment]::NewLine)[0])
+            }
+        }
+    }
+    function Get-ShrinkLiveControl {
+        # Return a live control connection, reopening it if the server dropped it (e.g. a restart).
+        param($Conn)
+        if ($Conn -and $Conn.State -eq 'Open') { return $Conn }
+        if ($Conn) { try { $Conn.Dispose() } catch {} }
+        (New-ShrinkConnection).Connection
+    }
+
+    # ----- pre-flight -----
+    $controlConn = New-ShrinkConnection
+    $control = $controlConn.Connection
+    $resolvedEntraMode = $controlConn.EntraMode
+    Write-ShrinkLog "Connected to [$DatabaseName] on [$ServerName]."
+
+    function Get-EligibleFiles {
+        param([Microsoft.Data.SqlClient.SqlConnection]$Conn)
+        $sql = @'
+SELECT df.file_id, df.name,
+       CAST(df.size / 128.0 AS bigint) AS alloc_mb,
+       CAST(FILEPROPERTY(df.name, 'SpaceUsed') / 128.0 AS bigint) AS used_mb
+FROM sys.database_files df
+JOIN sys.filegroups fg ON df.data_space_id = fg.data_space_id
+WHERE df.type_desc = 'ROWS' AND df.state_desc = 'ONLINE' AND fg.is_read_only = 0 AND df.is_read_only = 0;
+'@
+        $cmd = $Conn.CreateCommand(); $cmd.CommandText = $sql; $cmd.CommandTimeout = 120
+        $rd = $cmd.ExecuteReader()
+        $files = [System.Collections.Generic.List[object]]::new()
+        try {
+            while ($rd.Read()) {
+                $files.Add([pscustomobject]@{
+                        FileId = [int]$rd['file_id']; Name = [string]$rd['name']
+                        AllocatedMB = [long]$rd['alloc_mb']; UsedMB = [long]$rd['used_mb']; FloorMB = $floorMB
+                    })
+            }
+        } finally { $rd.Dispose(); $cmd.Dispose() }
+        $files
+    }
+
+    function Get-ShrinkFileSizes {
+        <# .SYNOPSIS Allocated and used size (MiB) for a set of data files, fetched in one query,
+           returned as a hashtable keyed by file_id. Batching avoids one FILEPROPERTY round-trip per
+           file: during heavy concurrent shrink, FILEPROPERTY('SpaceUsed') contends on the same file
+           latches the shrink holds, so many separate calls routinely time out. #>
+        param([Microsoft.Data.SqlClient.SqlConnection]$Conn, [int[]]$FileIds)
+        $sizes = @{}
+        if (-not $FileIds -or $FileIds.Count -eq 0) { return $sizes }
+        $cmd = $Conn.CreateCommand()
+        $cmd.CommandText = "SELECT file_id, size / 128.0 AS alloc_mb, ISNULL(FILEPROPERTY(name, 'SpaceUsed'), 0) / 128.0 AS used_mb FROM sys.database_files WHERE file_id IN ($($FileIds -join ','));"
+        # A single batched query still calls FILEPROPERTY('SpaceUsed') on files being shrunk, so it can
+        # latch-wait under heavy concurrency; give it a generous timeout (well under the status interval)
+        # so a transient wait delays one report at most rather than dropping it.
+        $cmd.CommandTimeout = 120
+        $rd = $cmd.ExecuteReader()
+        try {
+            while ($rd.Read()) { $sizes[[int]$rd['file_id']] = @{ Alloc = [double]$rd['alloc_mb']; Used = [double]$rd['used_mb'] } }
+        } finally { $rd.Dispose(); $cmd.Dispose() }
+        $sizes
+    }
+
+    function Get-ShrinkDatabaseTotals {
+        <# .SYNOPSIS Total allocated and used size (MiB) across the eligible (online, writable) ROWS files, in one query. #>
+        param([Microsoft.Data.SqlClient.SqlConnection]$Conn)
+        $sql = @'
+SELECT ISNULL(SUM(CAST(df.size AS bigint)) / 128.0, 0) AS alloc_mb,
+       ISNULL(SUM(CAST(ISNULL(FILEPROPERTY(df.name, 'SpaceUsed'), 0) AS bigint)) / 128.0, 0) AS used_mb
+FROM sys.database_files df
+JOIN sys.filegroups fg ON df.data_space_id = fg.data_space_id
+WHERE df.type_desc = 'ROWS' AND df.state_desc = 'ONLINE' AND fg.is_read_only = 0 AND df.is_read_only = 0;
+'@
+        $cmd = $Conn.CreateCommand(); $cmd.CommandText = $sql; $cmd.CommandTimeout = 60
+        $rd = $cmd.ExecuteReader()
+        try {
+            if ($rd.Read()) { @{ Alloc = [double]$rd['alloc_mb']; Used = [double]$rd['used_mb'] } } else { @{ Alloc = 0.0; Used = 0.0 } }
+        } finally { $rd.Dispose(); $cmd.Dispose() }
+    }
+
+    # Report mode: read the file sizes, print the shrink-potential report, and exit without
+    # shrinking. The shrink prerequisites below (SQL version, db_owner/sysadmin, AUTO_SHRINK) are
+    # skipped because this mode does not shrink anything, and reading file space usage from
+    # sys.database_files / FILEPROPERTY only needs the public role.
+    if ($Mode -eq 'Report') {
+        Write-ShrinkLog 'Report mode: analyzing reclaimable space; no files will be shrunk.'
+        $report = @(Get-EligibleFiles -Conn $control | ForEach-Object {
+                [pscustomobject]@{
+                    FileId = $_.FileId; Name = $_.Name; UsedMB = $_.UsedMB; AllocatedMB = $_.AllocatedMB
+                    ReclaimableMB = (Get-ShrinkReclaimableMB -AllocatedMB $_.AllocatedMB -UsedMB $_.UsedMB -FloorMB $floorMB)
+                    IsEligible = (Test-ShrinkWorthwhile -AllocatedMB $_.AllocatedMB -UsedMB $_.UsedMB -FloorMB $floorMB -MinReclaimMB $minReclaimMB)
+                }
+            })
+        Write-ShrinkLog '-------------------- shrink potential report --------------------'
+        Format-ShrinkFileReport -Files $report -TopN 100 | ForEach-Object { Write-ShrinkLog $_ }
+        $eligibleFiles = @($report | Where-Object { $_.IsEligible })
+        $sumUsed = Get-ShrinkSumMB -Items $report -Property UsedMB
+        $sumAlloc = Get-ShrinkSumMB -Items $report -Property AllocatedMB
+        # Report only the space a shrink with these settings would actually reclaim (the eligible
+        # files); files below the threshold are left as-is, so they don't count toward the total.
+        $sumRecl = Get-ShrinkSumMB -Items $eligibleFiles -Property ReclaimableMB
+        Write-ShrinkLog '-------------------- summary --------------------'
+        Format-ShrinkKeyValueTable -Rows ([ordered]@{
+                'Data files'             = $report.Count
+                'Eligible to shrink'     = $eligibleFiles.Count
+                'Used'                   = (Format-ShrinkSize $sumUsed)
+                'Allocated'              = (Format-ShrinkSize $sumAlloc)
+                'Reclaimable (eligible)' = (Format-ShrinkSize $sumRecl)
+            }) | ForEach-Object { Write-ShrinkLog $_ }
+        Write-ShrinkLog '-------------------------------------------------'
+        Write-ShrinkLog 'To shrink these files, run again with -Mode Shrink.'
+        $control.Close()
+        $reportResult = [pscustomobject]@{
+            Mode             = 'Report'
+            DataFiles        = $report.Count
+            Eligible         = $eligibleFiles.Count
+            TotalUsedMB      = $sumUsed
+            TotalAllocatedMB = $sumAlloc
+            ReclaimableMB    = $sumRecl
+            Files            = @($report | ForEach-Object { [pscustomobject]@{ FileId = $_.FileId; Name = $_.Name; UsedMB = $_.UsedMB; AllocatedMB = $_.AllocatedMB; ReclaimableMB = $_.ReclaimableMB; IsEligible = $_.IsEligible } })
+        }
+        if ($PassThru) { return $reportResult }
+        return
+    }
+
+    # Supported platforms only: SQL Server 2022 or later, Azure SQL Database, and Azure SQL Managed
+    # Instance. Read version, edition, permission, AUTO_SHRINK, and read-only checks in one round trip.
+    $pfCmd = $control.CreateCommand(); $pfCmd.CommandTimeout = 30
+    $pfCmd.CommandText = @'
+SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition,
+       CAST(SERVERPROPERTY('ProductMajorVersion') AS int) AS major_version,
+       CASE WHEN IS_ROLEMEMBER('db_owner') = 1 OR IS_SRVROLEMEMBER('sysadmin') = 1 THEN 1 ELSE 0 END AS has_perm,
+       CAST(DATABASEPROPERTYEX(DB_NAME(), 'IsAutoShrink') AS int) AS auto_shrink,
+       CASE WHEN DATABASEPROPERTYEX(DB_NAME(), 'Updateability') = 'READ_ONLY' THEN 1 ELSE 0 END AS read_only;
+'@
+    $pfRd = $pfCmd.ExecuteReader()
+    try {
+        [void]$pfRd.Read()
+        $engineEdition = [int]$pfRd['engine_edition']
+        $majorVersion = [int]$pfRd['major_version']
+        $hasPerm = [int]$pfRd['has_perm']
+        $autoShrink = [int]$pfRd['auto_shrink']
+        $dbReadOnly = [int]$pfRd['read_only']
+    } finally { $pfRd.Dispose(); $pfCmd.Dispose() }
+    if (-not ($engineEdition -in @(5, 8)) -and $majorVersion -lt 16) {
+        throw "ShrinkDriver supports only SQL Server 2022 or later, Azure SQL Database, and Azure SQL Managed Instance. Detected major version $majorVersion (EngineEdition $engineEdition), which is not supported."
+    }
+    if ($hasPerm -ne 1) { throw "The login must be a member of db_owner on [$DatabaseName] or sysadmin." }
+    if ($autoShrink -eq 1) {
+        throw "AUTO_SHRINK is ON for [$DatabaseName]. Disable it (ALTER DATABASE ... SET AUTO_SHRINK OFF) before running ShrinkDriver."
+    }
+    if ($dbReadOnly -eq 1) {
+        throw "Database [$DatabaseName] is read-only; its files cannot be shrunk."
+    }
+    if ($NoTruncate) {
+        Write-ShrinkLog 'NoTruncate moves data pages toward the front of each file without releasing space; the allocated size will not change (each file is reported as Repacked).'
+    }
+
+    $allFiles = @(Get-EligibleFiles -Conn $control)
+    $eligible = @($allFiles | Where-Object { Test-ShrinkWorthwhile -AllocatedMB $_.AllocatedMB -UsedMB $_.UsedMB -FloorMB $floorMB -MinReclaimMB $minReclaimMB })
+    $allocSum = [long](($allFiles | Measure-Object AllocatedMB -Sum).Sum)
+    $usedSum = [long](($allFiles | Measure-Object UsedMB -Sum).Sum)
+    Write-ShrinkLog ("Eligible data files: {0} of {1} (with at least {2} to reclaim). Total allocated {3}, used {4}, reclaimable {5}." -f `
+            $eligible.Count, $allFiles.Count, (Format-ShrinkSize $minReclaimMB),
+        (Format-ShrinkSize $allocSum), (Format-ShrinkSize $usedSum), (Format-ShrinkSize ($allocSum - $usedSum)))
+    if ($eligible.Count -eq 0) {
+        Write-ShrinkLog ("No files have at least {0} of space to reclaim above the target. Nothing to do." -f (Format-ShrinkSize $minReclaimMB))
+        $control.Close()
+        return [pscustomobject]@{
+            Mode          = 'Shrink'
+            Elapsed       = '0s'
+            StoppedBy     = $null
+            DbUsedMB      = $usedSum
+            DbAllocatedMB = $allocSum
+            Counts        = (Get-ShrinkBucketCounts -Buckets @())
+            Files         = @()
+        }
+    }
+    $effectiveSessions = [Math]::Min($Sessions, $eligible.Count)
+    if ($effectiveSessions -lt $Sessions) {
+        Write-ShrinkLog ("Capping concurrency to {0} (eligible file count) from requested {1}." -f $effectiveSessions, $Sessions) 'WARN'
+    }
+
+    # ----- shared state -----
+    $shared = [hashtable]::Synchronized(@{})
+    $shared.Files = [System.Collections.Generic.List[object]]::new(); $eligible | ForEach-Object { $shared.Files.Add($_) }
+    # Completed: every file that reached a terminal state this run, keyed by file id. The
+    # value records which bucket it landed in (Shrunk, PartlyShrunk, AlreadyMinimal,
+    # AlreadyAtTarget, Grew, GaveUp, Interrupted, or NotProcessed) plus an optional reason.
+    # Files listed here are never selected again.
+    $shared.Owned = @{}; $shared.Completed = @{}
+    # Sessions is read by the monitor thread and written by every worker (at startup and on each state
+    # change), so it must be thread-safe. A plain hashtable corrupts under concurrent writes, which can
+    # drop a worker's entry and make it throw (and die) before it ever starts a file. Owned/Completed
+    # stay plain hashtables because every access to them is already serialized by $shared.Lock.
+    $shared.Sessions = [System.Collections.Concurrent.ConcurrentDictionary[int, object]]::new()
+    $shared.Events = [System.Collections.Concurrent.ConcurrentQueue[string]]::new()
+    $shared.Stop = $false; $shared.StopReason = $null; $shared.Force = $false; $shared.Lock = [object]::new()
+
+    $connParams = @{
+        Server = $ServerName; Database = $DatabaseName; AuthType = $AuthType
+        SqlLogin = $SqlLogin; SqlPassword = $SqlPassword; EntraMode = $resolvedEntraMode
+        TrustAllowed = [bool]$TrustServerCertificate
+        TruncateOnly = [bool]$TruncateOnly; NoTruncate = [bool]$NoTruncate
+        Wlp = [bool]$WaitAtLowPriority; AbortAfterWait = $AbortAfterWait
+        FloorMB = $floorMB; StepMB = $stepMB; RetryCount = $RetryCount
+        MinReclaimMB = $minReclaimMB
+        BackoffBaseSec = $BackoffBaseSeconds; BackoffCapSec = $BackoffCapSeconds
+    }
+
+    $workerScript = {
+        param($workerId, $shared, $selfPath, $connParams)
+        . $selfPath
+        Set-StrictMode -Version Latest
+
+        function New-WConn {
+            $csb = [Microsoft.Data.SqlClient.SqlConnectionStringBuilder]::new()
+            $csb['Data Source'] = $connParams.Server; $csb['Initial Catalog'] = $connParams.Database
+            $csb['Encrypt'] = $true; $csb['Connect Timeout'] = 30; $csb['Application Name'] = "ShrinkDriver-w$workerId"
+            $csb['Pooling'] = $false   # dedicated, long-lived connection; close it for real on Dispose
+            $retry = New-ShrinkRetryProvider
+            switch ($connParams.AuthType) {
+                'Windows' {
+                    $csb['Integrated Security'] = $true
+                    Open-ShrinkSqlConnection -Builder $csb -RetryProvider $retry -AllowTrustServerCertificate $connParams.TrustAllowed
+                }
+                'SQL' {
+                    $pw = $connParams.SqlPassword.Copy(); $pw.MakeReadOnly()
+                    $cred = [Microsoft.Data.SqlClient.SqlCredential]::new($connParams.SqlLogin, $pw)
+                    Open-ShrinkSqlConnection -Builder $csb -Credential $cred -RetryProvider $retry -AllowTrustServerCertificate $connParams.TrustAllowed
+                }
+                default {
+                    $csb['Authentication'] = $connParams.EntraMode
+                    Open-ShrinkSqlConnection -Builder $csb -RetryProvider $retry -AllowTrustServerCertificate $false
+                }
+            }
+        }
+        function Emit($msg) { $shared.Events.Enqueue(('worker {0}: {1}' -f $workerId, $msg)) }
+        function Get-Size($conn, $fileId) {
+            $cmd = $conn.CreateCommand()
+            $cmd.CommandText = "SELECT CAST(size/128.0 AS bigint) AS a, CAST(FILEPROPERTY(name,'SpaceUsed')/128.0 AS bigint) AS u FROM sys.database_files WHERE file_id = $fileId;"
+            $rd = $cmd.ExecuteReader()
+            try { if ($rd.Read()) { @{ Alloc = [long]$rd['a']; Used = [long]$rd['u'] } } else { $null } }
+            finally { $rd.Dispose(); $cmd.Dispose() }
+        }
+        function Get-WConnResilient {
+            # Re-establish the worker connection, tolerating a server that is briefly offline (for
+            # example during an Azure SQL restart or failover). New-WConn's connection-level retry
+            # provider handles transient errors; this loop is the outer backstop that keeps trying,
+            # with backoff, for errors outside that list so a 1-2 minute outage does not kill the
+            # worker. On success it also refreshes the session's SPID (a reconnect gets a new one) so
+            # the status report keeps tracking the worker. Throws if it cannot reconnect in the bound.
+            $maxTries = [Math]::Max(10, [int]$connParams.RetryCount)
+            for ($try = 1; $try -le $maxTries; $try++) {
+                if ($shared.Stop) { throw [System.OperationCanceledException]::new('stop requested during reconnect') }
+                try {
+                    $newConn = New-WConn
+                    $spidCmd = $newConn.CreateCommand(); $spidCmd.CommandText = 'SELECT @@SPID'
+                    $newSpid = [int]$spidCmd.ExecuteScalar(); $spidCmd.Dispose()
+                    # Publish the new session id (a reconnect gets a fresh one) and mark the worker
+                    # live again so the status report tracks the right session. Reset ConnectTime too,
+                    # so the worker's Elapsed reflects its current connection; the run-wide elapsed is
+                    # shown separately in the database-total section.
+                    $shared.Sessions[$workerId].Spid = $newSpid
+                    $shared.Sessions[$workerId].State = 'Shrinking'
+                    $shared.Sessions[$workerId].ConnectTime = (Get-Date)
+                    Emit "reconnected on attempt $try (session ID $newSpid)"
+                    return $newConn
+                }
+                catch {
+                    if ($try -eq $maxTries) { throw }
+                    $w = Get-ShrinkBackoffSeconds -Attempt $try -BaseSec $connParams.BackoffBaseSec -CapSec $connParams.BackoffCapSec
+                    Emit "reconnect attempt $try/$maxTries failed ($($_.Exception.Message.Split([Environment]::NewLine)[0])); retrying in $([int]$w)s"
+                    Start-Sleep -Seconds $w
+                }
+            }
+        }
+
+        $conn = New-WConn
+        $spidCmd = $conn.CreateCommand(); $spidCmd.CommandText = 'SELECT @@SPID'
+        $spid = [int]$spidCmd.ExecuteScalar(); $spidCmd.Dispose()
+        $shared.Sessions[$workerId] = @{ Spid = $spid; Command = $null; FileId = $null; State = 'Idle'; ConnectTime = (Get-Date); RequestSeq = 0 }
+        Emit "Connected (session ID $spid)"
+
+        try {
+            while (-not $shared.Stop) {
+                $file = $null
+                [System.Threading.Monitor]::Enter($shared.Lock)
+                try {
+                    $file = Select-ShrinkNextFile -Files $shared.Files.ToArray() `
+                        -OwnedFileIds ([int[]]$shared.Owned.Keys) -ExcludedFileIds ([int[]]$shared.Completed.Keys)
+                    if ($file) { $shared.Owned[$file.FileId] = $workerId }
+                } finally { [System.Threading.Monitor]::Exit($shared.Lock) }
+                if (-not $file) { break }
+
+                $shared.Sessions[$workerId].FileId = $file.FileId
+                $shared.Sessions[$workerId].State = 'Shrinking'
+                Emit "Start file $($file.FileId) [$($file.Name)]"
+
+                $attempt = 0
+                $startAlloc = $null            # allocated size (MB) when this worker took the file
+                $bucket = $null                # terminal outcome: Shrunk | PartlyShrunk | AlreadyMinimal | AlreadyAtTarget | Grew | GaveUp
+                $bucketReason = $null          # detail text, recorded for the give-up outcomes
+                $connLost = $false             # set if the connection dropped and could not be re-established
+                while (-not $shared.Stop) {
+                    $sz = $null
+                    try { $sz = Get-Size $conn $file.FileId }
+                    catch [Microsoft.Data.SqlClient.SqlException] {
+                        if ($shared.Stop) { break }
+                        # The server dropped the connection between shrink steps; reconnect and retry.
+                        # Clear the (now dead) session id first so the status report does not match a
+                        # recycled spid to an unrelated session while we reconnect.
+                        Emit "File $($file.FileId) connection lost; reconnecting"
+                        $shared.Sessions[$workerId].Spid = $null
+                        $shared.Sessions[$workerId].State = 'Reconnecting'
+                        try { $conn.Dispose() } catch {}
+                        try { $conn = Get-WConnResilient }
+                        catch {
+                            # Could not reconnect within the bound. This is an external failure, not the
+                            # shrink running out of options, and the file's final size was not reassessed,
+                            # so classify it as Interrupted rather than GaveUp.
+                            $bucket = 'Interrupted'
+                            $bucketReason = "lost the connection to the server and could not reconnect: $($_.Exception.Message.Split([Environment]::NewLine)[0])"
+                            $connLost = $true
+                        }
+                        if ($connLost) { break }
+                        continue
+                    }
+                    if (-not $sz) { break }
+                    if ($null -eq $startAlloc) { $startAlloc = $sz.Alloc }
+
+                    if ($connParams.TruncateOnly) {
+                        $sql = New-ShrinkCommandText -FileId $file.FileId -TruncateOnly `
+                            -WaitAtLowPriority:$connParams.Wlp -AbortAfterWait $connParams.AbortAfterWait
+                    } else {
+                        # A shrink is long and expensive, so never launch one for a trivial gain: stop as
+                        # soon as less than MinReclaimMB of space can still be reclaimed, whether that floor
+                        # is the file's used pages or the requested target size.
+                        if (-not (Test-ShrinkWorthwhile -AllocatedMB $sz.Alloc -UsedMB $sz.Used -FloorMB $connParams.FloorMB -MinReclaimMB $connParams.MinReclaimMB)) {
+                            $atTarget = ($null -ne $connParams.FloorMB) -and ([long]$connParams.FloorMB -ge $sz.Used)
+                            if ($sz.Alloc -lt $startAlloc) {
+                                $bucket = 'Shrunk'
+                                $where = if ($atTarget) { 'target size' } else { 'its minimum size' }
+                                Emit "File $($file.FileId) shrunk to $where, now $(Format-ShrinkSize $sz.Alloc)"
+                            } elseif ($atTarget) {
+                                $bucket = 'AlreadyAtTarget'
+                                Emit "File $($file.FileId) already at or below target size ($(Format-ShrinkSize $sz.Alloc)); nothing to do"
+                            } else {
+                                $bucket = 'AlreadyMinimal'
+                                Emit "File $($file.FileId) already at its minimum size ($(Format-ShrinkSize $sz.Alloc)); nothing to reclaim"
+                            }
+                            break
+                        }
+                        $next = Get-ShrinkNextTargetMB -AllocatedMB $sz.Alloc -FloorMB $connParams.FloorMB -StepMB $connParams.StepMB
+                        $sql = New-ShrinkCommandText -FileId $file.FileId -TargetMB $next `
+                            -NoTruncate:$connParams.NoTruncate -WaitAtLowPriority:$connParams.Wlp -AbortAfterWait $connParams.AbortAfterWait
+                    }
+
+                    $cmd = $conn.CreateCommand(); $cmd.CommandText = $sql; $cmd.CommandTimeout = 0
+                    # A new DBCC SHRINKFILE step is a new request, so its per-request cpu_time/reads/writes
+                    # counters restart at zero. Bump the sequence the status report uses to key its deltas
+                    # so it only differences counters within one request, never across a step boundary.
+                    $shared.Sessions[$workerId].RequestSeq++
+                    $shared.Sessions[$workerId].Command = $cmd
+                    $before = $sz.Alloc
+                    try {
+                        # DBCC SHRINKFILE returns a one-row result set; read CurrentSize from it to learn
+                        # the file's size after the attempt without a second round trip.
+                        $result = $null
+                        $rd = $cmd.ExecuteReader()
+                        try {
+                            if ($rd.Read()) {
+                                $result = @{ CurrentMB = ([double][long]$rd['CurrentSize']) / 128.0 }
+                            }
+                        } finally { $rd.Dispose() }
+
+                        if ($connParams.TruncateOnly) {
+                            $after = if ($result) { [long]$result.CurrentMB } else { (Get-Size $conn $file.FileId).Alloc }
+                            if ($after -lt $startAlloc) {
+                                $bucket = 'Shrunk'
+                                Emit "File $($file.FileId) truncated to $(Format-ShrinkSize $after)"
+                            } else {
+                                $bucket = 'AlreadyMinimal'
+                                Emit "File $($file.FileId) had no unused space to truncate ($(Format-ShrinkSize $after))"
+                            }
+                            break
+                        }
+
+                        if ($connParams.NoTruncate) {
+                            # NoTruncate moves allocated pages toward the front of the file but never
+                            # releases space, so the allocated size is unchanged by design. Treat a
+                            # completed pass as its own success (Repacked) rather than a give-up, and do
+                            # not loop: a second pass would not reduce the size either.
+                            $bucket = 'Repacked'
+                            Emit "File $($file.FileId) repacked; NoTruncate leaves the allocated size unchanged ($(Format-ShrinkSize $before))"
+                            break
+                        }
+
+                        $after = if ($result) { [long]$result.CurrentMB } else { (Get-Size $conn $file.FileId).Alloc }
+                        if ($after -lt $before) {
+                            # Made progress this pass; keep shrinking.
+                            $attempt = 0
+                        }
+                        elseif ($after -gt $before) {
+                            # The file grew during this pass (other workloads added data). Growth can be
+                            # transient, so back off and retry up to the limit before giving up.
+                            $attempt++
+                            if ($attempt -gt $connParams.RetryCount) {
+                                if ($after -gt $startAlloc) {
+                                    $bucket = 'Grew'
+                                    $bucketReason = "grew from $(Format-ShrinkSize $startAlloc) to $(Format-ShrinkSize $after) during the shrink (other workloads adding data); gave up after $($connParams.RetryCount) retries"
+                                    Emit "File $($file.FileId) grew to $(Format-ShrinkSize $after) during the shrink (other workloads adding data); gave up"
+                                } else {
+                                    $bucket = 'PartlyShrunk'
+                                    $bucketReason = "reduced from $(Format-ShrinkSize $startAlloc) to $(Format-ShrinkSize $after) but kept growing during the shrink; gave up after $($connParams.RetryCount) retries"
+                                    Emit "File $($file.FileId) partly shrunk to $(Format-ShrinkSize $after), then gave up: the file kept growing during the shrink"
+                                }
+                                break
+                            }
+                            $wait = Get-ShrinkBackoffSeconds -Attempt $attempt -BaseSec $connParams.BackoffBaseSec -CapSec $connParams.BackoffCapSec
+                            Emit "File $($file.FileId) grew during the shrink; retry $attempt in $([int]$wait)s"
+                            Start-Sleep -Seconds $wait
+                        }
+                        else {
+                            # No progress, yet the pre-check confirmed there was more than MinReclaimMB of
+                            # unused space to reclaim. Retrying has no high confidence of helping.
+                            # Stop and report a partial result.
+                            if ($after -lt $startAlloc) {
+                                $bucket = 'PartlyShrunk'
+                                $bucketReason = "reduced from $(Format-ShrinkSize $startAlloc) to $(Format-ShrinkSize $after), but the remaining unused space could not be reclaimed"
+                                Emit "File $($file.FileId) partly shrunk to $(Format-ShrinkSize $after); the remaining unused space could not be reclaimed"
+                            } else {
+                                $bucket = 'GaveUp'
+                                $bucketReason = "the shrink could not reclaim any of the unused space"
+                                Emit "Gave up on file $($file.FileId): $bucketReason"
+                            }
+                            break
+                        }
+                    } catch [Microsoft.Data.SqlClient.SqlException] {
+                        if ($shared.Stop) { break }
+                        $num = $_.Exception.Number
+                        if ($num -eq 5201) {
+                            if ($before -lt $startAlloc) {
+                                $bucket = 'Shrunk'
+                                Emit "File $($file.FileId) shrunk to $(Format-ShrinkSize $before) (MSSQL 5201: no more reclaimable space)"
+                            } else {
+                                $bucket = 'AlreadyMinimal'
+                                Emit "File $($file.FileId) cannot be shrunk (MSSQL error 5201: no reclaimable space)"
+                            }
+                            break
+                        }
+                        if ($conn.State -ne 'Open') {
+                            # The connection dropped (server restart, failover, or the client machine
+                            # sleeping). Reconnecting is not a per-file failure, so it does not count
+                            # against the retry budget; Get-WConnResilient has its own bound. Clear the
+                            # dead session id first so the status report does not match a recycled spid.
+                            Emit "File $($file.FileId) connection lost (MSSQL error $num); reconnecting"
+                            $shared.Sessions[$workerId].Spid = $null
+                            $shared.Sessions[$workerId].State = 'Reconnecting'
+                            try { $conn.Dispose() } catch {}
+                            try { $conn = Get-WConnResilient }
+                            catch {
+                                # External failure, not a shrink that ran out of options: the last DBCC step
+                                # may have been mid-flight, so the final size is unknown. Classify as Interrupted.
+                                $bucket = 'Interrupted'
+                                $bucketReason = "lost the connection to the server and could not reconnect: $($_.Exception.Message.Split([Environment]::NewLine)[0])"
+                                Emit "File $($file.FileId) interrupted: $bucketReason"
+                                $connLost = $true; break
+                            }
+                        }
+                        else {
+                            # The connection is still up but the command failed transiently; retry the
+                            # file up to the retry budget with backoff.
+                            $attempt++
+                            if ($attempt -gt $connParams.RetryCount) {
+                                $bucket = Get-ShrinkGaveUpBucket -StartAllocMB $startAlloc -FinalAllocMB $before
+                                $bucketReason = "MSSQL error $num after $($connParams.RetryCount) retries: $($_.Exception.Message.Split([Environment]::NewLine)[0])"
+                                Emit "Gave up on file $($file.FileId): $bucketReason"; break
+                            }
+                            $wait = Get-ShrinkBackoffSeconds -Attempt $attempt -BaseSec $connParams.BackoffBaseSec -CapSec $connParams.BackoffCapSec
+                            Emit "File $($file.FileId) MSSQL error $num (retry $attempt in $([int]$wait)s): $($_.Exception.Message.Split([Environment]::NewLine)[0])"
+                            Start-Sleep -Seconds $wait
+                        }
+                    } finally {
+                        $shared.Sessions[$workerId].Command = $null
+                        try { $cmd.Dispose() } catch {}
+                    }
+                }
+
+                # If the run was stopped while this file was still in progress, decide how to record it.
+                # An early stop that is not a forced quit (the run time limit, or the first Ctrl+C) is an
+                # orderly wind-down: reassess the file and report its real outcome - DBCC SHRINKFILE keeps
+                # the space it reclaimed even when cancelled, so a fresh measurement is authoritative. A
+                # forced quit (second Ctrl+C) or a lost connection leaves the file Interrupted instead.
+                if (-not $bucket -and $shared.Stop) {
+                    $cause = if ($shared.StopReason -eq 'Timeout') { 'Timeout' } else { 'Ctrl+C' }
+                    # Re-measure the file's real size (unless force-quitting or the connection is gone).
+                    # DBCC SHRINKFILE keeps the space it reclaimed even when cancelled, so a fresh read is
+                    # authoritative. Track the command so a second Ctrl+C can cancel it if the server hangs.
+                    $final = $null
+                    if (-not $shared.Force -and $null -ne $startAlloc -and $conn.State -eq 'Open') {
+                        try {
+                            $mcmd = $conn.CreateCommand()
+                            $mcmd.CommandText = "SELECT CAST(size/128.0 AS bigint) FROM sys.database_files WHERE file_id = $($file.FileId);"
+                            $shared.Sessions[$workerId].Command = $mcmd
+                            $final = [long]$mcmd.ExecuteScalar()
+                            $shared.Sessions[$workerId].Command = $null; $mcmd.Dispose()
+                        } catch { $shared.Sessions[$workerId].Command = $null; $final = $null }
+                    }
+                    $outcome = Get-ShrinkStopOutcome -StartAllocMB $startAlloc -FinalAllocMB $final -Cause $cause -Force:([bool]$shared.Force)
+                    $bucket = $outcome.Bucket; $bucketReason = $outcome.Reason
+                }
+
+                [System.Threading.Monitor]::Enter($shared.Lock)
+                try {
+                    $shared.Owned.Remove($file.FileId)
+                    if ($bucket) { $shared.Completed[$file.FileId] = @{ Bucket = $bucket; Reason = $bucketReason } }
+                } finally { [System.Threading.Monitor]::Exit($shared.Lock) }
+                $shared.Sessions[$workerId].FileId = $null; $shared.Sessions[$workerId].State = 'Idle'
+                if ($connLost) { Emit 'connection lost and not recoverable; worker stopping'; break }
+            }
+        }
+        catch {
+            # Surface why a worker dies instead of failing silently - otherwise the error is only seen
+            # at run end via EndInvoke. The worker then exits cleanly through the finally below.
+            Emit "worker failed: $($_.Exception.Message.Split([Environment]::NewLine)[0])"
+        }
+        finally {
+            # Release any file this worker still owns (e.g. if it died mid-file) so another can retry it.
+            [System.Threading.Monitor]::Enter($shared.Lock)
+            try { foreach ($fid in @($shared.Owned.Keys)) { if ($shared.Owned[$fid] -eq $workerId) { $shared.Owned.Remove($fid) } } }
+            finally { [System.Threading.Monitor]::Exit($shared.Lock) }
+            # Clear the session id: once this connection is disposed the server can recycle its
+            # session_id for an unrelated (e.g. internal) task, and a lingering id would make the
+            # status report match that stranger's request. Nulling it (as on reconnect) drops the
+            # worker from the live-spid query and shows it as SPID '-', Stopped.
+            $shared.Sessions[$workerId].Spid = $null; $shared.Sessions[$workerId].FileId = $null
+            $shared.Sessions[$workerId].State = 'Stopped'
+            try { $conn.Dispose() } catch {}
+            Emit 'stopped'
+        }
+    }
+
+    # ----- launch workers -----
+    $iss = [initialsessionstate]::CreateDefault()
+    $pool = [runspacefactory]::CreateRunspacePool(1, $effectiveSessions, $iss, $Host)
+    $pool.Open()
+    $workers = for ($workerId = 0; $workerId -lt $effectiveSessions; $workerId++) {
+        $ps = [powershell]::Create(); $ps.RunspacePool = $pool
+        [void]$ps.AddScript($workerScript).AddArgument($workerId).AddArgument($shared).AddArgument($selfPath).AddArgument($connParams)
+        [pscustomobject]@{ WorkerId = $workerId; PS = $ps; Handle = $ps.BeginInvoke() }
+    }
+    Write-ShrinkLog "Launched $effectiveSessions worker session(s)."
+
+    # Graceful Ctrl+C: do NOT use a Console.CancelKeyPress handler - PowerShell raises that event on
+    # a background thread with no runspace, so a script handler throws and crashes the process. Make
+    # Ctrl+C an ordinary key instead and poll for it on this (runspace) thread in the monitor loop.
+    # Restored in the finally block. Only do this when we are attached to a console we can read keys from.
+    $ctrlCAsInput = $false
+    $prevTreatCtrlC = $false
+    if (-not [Console]::IsInputRedirected) {
+        try { $prevTreatCtrlC = [Console]::TreatControlCAsInput; [Console]::TreatControlCAsInput = $true; $ctrlCAsInput = $true } catch {}
+    }
+
+    # ----- monitor loop -----
+    $startTime = Get-Date
+    $deadline = if ($null -ne $MaxRuntimeSecondsOverride) { $startTime.AddSeconds([int]$MaxRuntimeSecondsOverride) } elseif ($null -ne $MaxRuntimeMinutes) { $startTime.AddMinutes([int]$MaxRuntimeMinutes) } else { $null }
+    $prev = @{}; $stuckState = @{}
+
+    function Write-StatusReport {
+        $evt = ''
+        while ($shared.Events.TryDequeue([ref]$evt)) { Write-ShrinkLog $evt 'EVENT' }
+        $spids = @($shared.Sessions.Values | Where-Object { $_.Spid } | ForEach-Object { [int]$_.Spid })
+        $rows = [System.Collections.Generic.List[object]]::new()
+        # Query only for workers that currently have a live session id. A worker mid-reconnect has
+        # none (its spid was cleared), so it is shown from its shared state instead - this avoids
+        # matching a stale, recycled spid to an unrelated system session.
+        if ($spids.Count -gt 0) {
+            $inList = ($spids -join ',')
+            $sql = @"
+SELECT r.session_id, r.status, r.command, ISNULL(r.wait_type,'') AS wait_type, r.wait_time,
+       r.percent_complete, r.cpu_time, r.reads, r.writes, ISNULL(r.blocking_session_id,0) AS blocker,
+       ISNULL((SELECT TOP 1 b.command FROM sys.dm_exec_requests b WHERE b.session_id = r.blocking_session_id),'') AS blocker_cmd
+FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
+"@
+            $cmd = $control.CreateCommand(); $cmd.CommandText = $sql; $cmd.CommandTimeout = 60
+            $rd = $cmd.ExecuteReader()
+            try { while ($rd.Read()) { $rows.Add([pscustomobject]@{
+                            Spid = [int]$rd['session_id']; Status = [string]$rd['status']; Command = [string]$rd['command']
+                            Wait = [string]$rd['wait_type']; WaitTime = [long]$rd['wait_time']; Pct = [double]$rd['percent_complete']
+                            Cpu = [long]$rd['cpu_time']; Reads = [long]$rd['reads']; Writes = [long]$rd['writes']; Blocker = [int]$rd['blocker']; BlockerCmd = [string]$rd['blocker_cmd']
+                        }) } } finally { $rd.Dispose(); $cmd.Dispose() }
+        }
+
+        Write-ShrinkLog '---- status ----'
+        # Fetch every in-flight file's size in one query rather than one FILEPROPERTY round-trip per
+        # worker: FILEPROPERTY('SpaceUsed') contends on the same file latches the shrink holds, so
+        # under high concurrency the per-file calls time out and the whole report is dropped.
+        $statusFileIds = @($shared.Sessions.Values | Where-Object { $_.FileId } | ForEach-Object { [int]$_.FileId } | Sort-Object -Unique)
+        $sizeById = Get-ShrinkFileSizes -Conn $control -FileIds $statusFileIds
+        $statusData = [System.Collections.Generic.List[object]]::new()
+        foreach ($sess in $shared.Sessions.GetEnumerator() | Sort-Object { $_.Key }) {
+            $workerId = $sess.Key; $s = $sess.Value
+            $seq = [int]$s.RequestSeq
+            # Elapsed is the worker's wall-clock time on its current connection (it resets when the
+            # worker reconnects). The run-wide elapsed since script start is in the database-total section.
+            $sessElapsedS = if ($s.ConnectTime) { [int]((Get-Date) - [datetime]$s.ConnectTime).TotalSeconds } else { $null }
+            $row = $rows | Where-Object Spid -eq $s.Spid | Select-Object -First 1
+            if (-not $row) {
+                $statusData.Add([pscustomobject]@{
+                        Worker = $workerId; Spid = $s.Spid; FileId = $s.FileId; UsedMB = $null; AllocMB = $null
+                        Cmd = ''; Status = $s.State; Pct = $null; ElapsedS = $sessElapsedS; Increment = $seq
+                        Wait = ''; DCpu = '-'; DReads = '-'; DWrites = '-'; Blocker = ''
+                    })
+                continue
+            }
+            # cpu_time/reads/writes in dm_exec_requests are per-request and restart on each new shrink step,
+            # so a delta is only meaningful when the increment is unchanged since the last report; otherwise
+            # show '-'.
+            $dCpu = '-'; $dReads = '-'; $dWrites = '-'
+            if ($prev.ContainsKey($s.Spid) -and $prev[$s.Spid].Seq -eq $seq) {
+                $c = Get-ShrinkDeltaWithReset -Previous $prev[$s.Spid].Cpu -Current $row.Cpu
+                $rr = Get-ShrinkDeltaWithReset -Previous $prev[$s.Spid].Reads -Current $row.Reads
+                $rw = Get-ShrinkDeltaWithReset -Previous $prev[$s.Spid].Writes -Current $row.Writes
+                $dCpu = if ($c.IsReset) { '-' } else { '{0:N0}' -f $c.Delta }
+                $dReads = if ($rr.IsReset) { '-' } else { '{0:N0}' -f $rr.Delta }
+                $dWrites = if ($rw.IsReset) { '-' } else { '{0:N0}' -f $rw.Delta }
+            }
+            $prev[$s.Spid] = @{ Seq = $seq; Cpu = $row.Cpu; Reads = $row.Reads; Writes = $row.Writes }
+            $z = if ($s.FileId -and $sizeById.ContainsKey([int]$s.FileId)) { $sizeById[[int]$s.FileId] } else { $null }
+            $statusData.Add([pscustomobject]@{
+                    Worker = $workerId; Spid = $s.Spid; FileId = $s.FileId
+                    UsedMB = $(if ($z) { $z.Used } else { $null }); AllocMB = $(if ($z) { $z.Alloc } else { $null })
+                    Cmd = $row.Command; Status = $row.Status; Pct = [math]::Round($row.Pct, 1); ElapsedS = $sessElapsedS; Increment = $seq
+                    Wait = $(if ($row.Wait) { "$($row.Wait) $($row.WaitTime)ms" } else { '' })
+                    DCpu = $dCpu; DReads = $dReads; DWrites = $dWrites
+                    Blocker = $(if ($row.Blocker) { "$($row.Blocker) ($($row.BlockerCmd))" } else { '' })
+                })
+
+            if (-not $stuckState.ContainsKey($s.Spid)) { $stuckState[$s.Spid] = @{ Blocker = 0; Cpu = 0; Reads = 0; BlockerSince = $null; NoProgressSince = $null } }
+            $st = Update-ShrinkStuckState -State $stuckState[$s.Spid] -Blocker $row.Blocker -Cpu $row.Cpu -Reads $row.Reads -Now (Get-Date) -WindowSec $StuckWindowSeconds
+            if ($st.IsStuck -and $s.Command) {
+                $why = if ($st.BlockerStuck -and $row.Blocker) { "blocked by session $($row.Blocker)" } else { 'no CPU or read progress' }
+                Write-ShrinkLog ("worker {0} session ID {1} stuck ({2}) for >= {3}s: cancelling command." -f $workerId, $s.Spid, $why, $StuckWindowSeconds) 'WARN'
+                try { $s.Command.Cancel() } catch {}
+                $stuckState[$s.Spid].BlockerSince = $null
+                $stuckState[$s.Spid].NoProgressSince = $null
+            }
+        }
+        # Render the collected worker rows as one aligned table, using a single size unit chosen from
+        # the largest allocation so the used/allocated columns never mix units across workers.
+        $maxMb = 0.0
+        foreach ($d in $statusData) { if ($null -ne $d.AllocMB -and [double]$d.AllocMB -gt $maxMb) { $maxMb = [double]$d.AllocMB } }
+        $unit = Get-ShrinkSizeUnit -MaxMegabytes $maxMb
+        $numFmt = '{0:N' + $unit.Decimals + '}'
+        $usedHdr = "Used ($($unit.Name))"; $allocHdr = "Alloc ($($unit.Name))"
+        $statusTable = foreach ($d in $statusData) {
+            [ordered]@{
+                Worker    = [string]$d.Worker
+                SPID      = $(if ($null -ne $d.Spid) { [string]$d.Spid } else { '-' })
+                File      = $(if ($d.FileId) { [string]$d.FileId } else { '-' })
+                $usedHdr  = $(if ($null -ne $d.UsedMB) { $numFmt -f ([double]$d.UsedMB / $unit.PerMB) } else { '' })
+                $allocHdr = $(if ($null -ne $d.AllocMB) { $numFmt -f ([double]$d.AllocMB / $unit.PerMB) } else { '' })
+                '%Done'   = $(if ($null -ne $d.Pct) { [string]$d.Pct } else { '' })
+                Elapsed   = $(if ($null -ne $d.ElapsedS) { Format-ShrinkDuration -TimeSpan ([TimeSpan]::FromSeconds($d.ElapsedS)) } else { '' })
+                Increment = [string]$d.Increment
+                Cmd       = [string]$d.Cmd
+                Status    = [string]$d.Status
+                dCPU      = [string]$d.DCpu
+                dReads    = [string]$d.DReads
+                dWrites   = [string]$d.DWrites
+                Blocker   = $(if ($d.Blocker) { [string]$d.Blocker } else { '-' })
+                Wait      = [string]$d.Wait
+            }
+        }
+        Format-ShrinkTable -Rows @($statusTable) -RightAlign @('Worker', 'SPID', 'File', $usedHdr, $allocHdr, '%Done', 'Elapsed', 'Increment', 'dCPU', 'dReads', 'dWrites') |
+            ForEach-Object { Write-ShrinkLog $_ }
+        $tot = Get-ShrinkDatabaseTotals -Conn $control
+        $dbUsedMb = $tot.Used; $dbAllocMb = $tot.Alloc
+        [System.Threading.Monitor]::Enter($shared.Lock)
+        try { $buckets = @($shared.Completed.Values | ForEach-Object { $_.Bucket }) } finally { [System.Threading.Monitor]::Exit($shared.Lock) }
+        $c = Get-ShrinkBucketCounts -Buckets $buckets
+        Write-ShrinkLog '---- database total ----'
+        Format-ShrinkKeyValueTable -Rows (Get-ShrinkTotalsRows `
+                -RunTime (Format-ShrinkDuration -TimeSpan ((Get-Date) - $startTime)) `
+                -Used (Format-ShrinkSize $dbUsedMb) -Allocated (Format-ShrinkSize $dbAllocMb) -Counts $c) |
+            ForEach-Object { Write-ShrinkLog $_ }
+    }
+
+    # Poll frequently so worker events (connects, file starts, retries, give-ups) surface
+    # promptly, but run the heavier per-file status report only every StatusIntervalSeconds
+    # (with the first one shortly after startup so progress shows without a long initial wait).
+    $pollSeconds = [Math]::Max(1, [Math]::Min(2, $StatusIntervalSeconds))
+    $nextReport = (Get-Date).AddSeconds([Math]::Min(15, $StatusIntervalSeconds))
+    try {
+        while ($true) {
+            $evt = ''
+            while ($shared.Events.TryDequeue([ref]$evt)) { Write-ShrinkLog $evt 'EVENT' }
+            if ($ctrlCAsInput -and [Console]::KeyAvailable) {
+                $k = [Console]::ReadKey($true)
+                if ($k.Key -eq [ConsoleKey]::C -and ($k.Modifiers -band [ConsoleModifiers]::Control)) {
+                    if (-not $shared.Stop) {
+                        # First Ctrl+C: stop early but still report what each in-flight file achieved, just
+                        # like the run time limit. Keep listening so a second press can be caught.
+                        Write-ShrinkLog 'Ctrl+C received: stopping early and recording each in-flight file''s current state. Press Ctrl+C again to stop immediately.' 'WARN'
+                        $shared.StopReason = 'Ctrl+C'
+                        $shared.Stop = $true
+                        foreach ($sess in $shared.Sessions.Values) { if ($sess.Command) { try { $sess.Command.Cancel() } catch {} } }
+                    } else {
+                        # Second Ctrl+C: don't wait to reassess (the server may be unresponsive); report the
+                        # in-flight files as Interrupted. Cancel any measurement in progress, then restore the
+                        # default handler so a further press can force-quit a truly wedged process.
+                        Write-ShrinkLog 'Ctrl+C received again: stopping immediately; in-flight files are reported as Interrupted.' 'WARN'
+                        $shared.Force = $true
+                        foreach ($sess in $shared.Sessions.Values) { if ($sess.Command) { try { $sess.Command.Cancel() } catch {} } }
+                        try { [Console]::TreatControlCAsInput = $prevTreatCtrlC } catch {}
+                        $ctrlCAsInput = $false
+                    }
+                }
+            }
+            if ((Get-Date) -ge $nextReport) {
+                # The status report reads through the control connection; if the server dropped it
+                # (e.g. a restart), reopen it and skip just this report rather than failing the run.
+                try {
+                    $control = Get-ShrinkLiveControl $control
+                    Write-StatusReport
+                }
+                catch {
+                    Write-ShrinkLog ("Status report skipped (control connection issue): {0}" -f $_.Exception.Message.Split([Environment]::NewLine)[0]) 'WARN'
+                    try { $control = Get-ShrinkLiveControl $control } catch { Write-ShrinkLog ("Control reconnect failed; will retry at the next report: {0}" -f $_.Exception.Message.Split([Environment]::NewLine)[0]) 'WARN' }
+                }
+                $nextReport = (Get-Date).AddSeconds($StatusIntervalSeconds)
+            }
+            if (-not ($workers | Where-Object { -not $_.Handle.IsCompleted })) { Write-ShrinkLog 'All workers finished.'; break }
+            if ($deadline -and (Get-Date) -ge $deadline -and -not $shared.Stop) {
+                Write-ShrinkLog 'Run time limit reached: stopping and recording each in-flight file''s current state.' 'WARN'
+                $shared.StopReason = 'Timeout'
+                $shared.Stop = $true
+                foreach ($sess in $shared.Sessions.Values) { if ($sess.Command) { try { $sess.Command.Cancel() } catch {} } }
+            }
+            Start-Sleep -Seconds $pollSeconds
+        }
+    } finally {
+        if ($ctrlCAsInput) { try { [Console]::TreatControlCAsInput = $prevTreatCtrlC } catch {} }
+        foreach ($w in $workers) {
+            try { $w.PS.EndInvoke($w.Handle) | Out-Null } catch { Write-ShrinkLog "Worker $($w.WorkerId) error: $($_.Exception.Message)" 'WARN' }
+            $w.PS.Dispose()
+        }
+        $pool.Close(); $pool.Dispose()
+        # Flush any worker events that arrived after the last poll, then write a single final summary.
+        $evt = ''
+        while ($shared.Events.TryDequeue([ref]$evt)) { Write-ShrinkLog $evt 'EVENT' }
+        $elapsed = Format-ShrinkDuration -TimeSpan ((Get-Date) - $startTime)
+        # The final totals need a live control connection; if the server dropped it (e.g. a restart),
+        # try once to reopen, but never let that stop us from writing the outcome summary.
+        $dbUsedMb = $null; $dbAllocMb = $null
+        try {
+            $control = Get-ShrinkLiveControl $control
+            $tot = Get-ShrinkDatabaseTotals -Conn $control
+            $dbUsedMb = $tot.Used; $dbAllocMb = $tot.Alloc
+        } catch { Write-ShrinkLog ("Could not read final database totals: {0}" -f $_.Exception.Message.Split([Environment]::NewLine)[0]) 'WARN' }
+        # Reconcile: any eligible file that never reached a terminal state (e.g. left unprocessed after
+        # an unrecoverable outage, or never started) is recorded as NotProcessed, so the summary reflects
+        # every eligible file instead of silently implying the run finished them all.
+        [System.Threading.Monitor]::Enter($shared.Lock)
+        try {
+            foreach ($f in $shared.Files) {
+                if (-not $shared.Completed.ContainsKey($f.FileId)) {
+                    $shared.Completed[$f.FileId] = @{ Bucket = 'NotProcessed'; Reason = 'eligible but not processed before the run ended' }
+                }
+            }
+        } finally { [System.Threading.Monitor]::Exit($shared.Lock) }
+        $c = Get-ShrinkBucketCounts -Buckets @($shared.Completed.Values | ForEach-Object { $_.Bucket })
+        Write-ShrinkLog '-------------------- summary --------------------'
+        Format-ShrinkKeyValueTable -Rows (Get-ShrinkTotalsRows -RunTime $elapsed `
+                -Used $(if ($null -ne $dbUsedMb) { Format-ShrinkSize $dbUsedMb } else { '(unavailable)' }) `
+                -Allocated $(if ($null -ne $dbAllocMb) { Format-ShrinkSize $dbAllocMb } else { '(unavailable)' }) -Counts $c) |
+            ForEach-Object { Write-ShrinkLog $_ }
+        foreach ($r in $shared.Completed.GetEnumerator() | Sort-Object { [int]$_.Key }) { if ($r.Value.Reason) { Write-ShrinkLog ("  file {0} [{1}]: {2}" -f $r.Key, $r.Value.Bucket, $r.Value.Reason) } }
+        Write-ShrinkLog '-------------------------------------------------'
+        # Structured result for programmatic callers / tests (the log/console is unchanged).
+        $runResult = [pscustomobject]@{
+            Mode          = 'Shrink'
+            Elapsed       = $elapsed
+            StoppedBy     = $shared.StopReason
+            DbUsedMB      = $dbUsedMb
+            DbAllocatedMB = $dbAllocMb
+            Counts        = $c
+            Files         = @($shared.Completed.GetEnumerator() | Sort-Object { [int]$_.Key } | ForEach-Object { [pscustomobject]@{ FileId = [int]$_.Key; Bucket = $_.Value.Bucket; Reason = $_.Value.Reason } })
+        }
+        try { $control.Close() } catch {}
+        try { $control.Dispose() } catch {}
+    }
+    }
+    catch {
+        Write-ShrinkLog "Fatal error [$($_.Exception.GetType().Name)]: $($_.Exception.Message)" 'ERROR'
+        throw
+    }
+    finally {
+        # Safety net: make sure the control connection is closed on every exit path (report/return, a
+        # pre-flight failure, or a fatal error), not just the normal monitor-loop shutdown.
+        if ($control) { try { $control.Dispose() } catch {} }
+    }
+    if ($PassThru) { $runResult }
+}
+
+# ----- internal helper functions (used by Invoke-ShrinkDriver and the worker runspaces) -----
+
+function New-ShrinkRetryProvider {
+    <# .SYNOPSIS
+      Build a Microsoft.Data.SqlClient connection-retry provider (exponential backoff with jitter)
+      for transient connection-open failures, such as an Azure SQL restart or failover. This is a
+      short, shallow inner retry that only smooths reopening; the caller's own retry loop remains
+      the outer backstop for errors this provider's transient list does not cover. Returns $null
+      when the driver predates configurable retry (Microsoft.Data.SqlClient earlier than 3.0). #>
+    [CmdletBinding()]
+    param(
+        [int]$NumberOfTries = 5,
+        [int]$DeltaSeconds = 4,
+        [int]$MaxIntervalSeconds = 30
+    )
+    if (-not ('Microsoft.Data.SqlClient.SqlConfigurableRetryFactory' -as [type])) { return $null }
+    $opt = [Microsoft.Data.SqlClient.SqlRetryLogicOption]::new()
+    $opt.NumberOfTries = $NumberOfTries
+    $opt.DeltaTime = [TimeSpan]::FromSeconds($DeltaSeconds)
+    $opt.MaxTimeInterval = [TimeSpan]::FromSeconds($MaxIntervalSeconds)
+    # Leave TransientErrors unset so the provider uses the driver's own maintained default list of
+    # transient error numbers (Azure SQL restart/failover/throttling and transport drops). Our own
+    # retry loop is a broad catch-all backstop for anything the default list happens to omit.
+    [Microsoft.Data.SqlClient.SqlConfigurableRetryFactory]::CreateExponentialRetryProvider($opt)
+}
+
+function Open-ShrinkSqlConnection {
+    <# .SYNOPSIS
+      Open a SqlConnection from a connection-string builder, validating the server's certificate. The
+      first attempt always validates the certificate; only if it fails and $AllowTrustServerCertificate
+      is set does it retry once trusting the certificate. #>
+    [CmdletBinding()][OutputType([Microsoft.Data.SqlClient.SqlConnection])]
+    param(
+        [Parameter(Mandatory)][Microsoft.Data.SqlClient.SqlConnectionStringBuilder]$Builder,
+        [Microsoft.Data.SqlClient.SqlCredential]$Credential,
+        [object]$RetryProvider,
+        [bool]$AllowTrustServerCertificate
+    )
+    foreach ($trust in @($false, $true)) {
+        if ($trust) { $Builder['TrustServerCertificate'] = $true } else { [void]$Builder.Remove('TrustServerCertificate') }
+        $conn = [Microsoft.Data.SqlClient.SqlConnection]::new()
+        $conn.ConnectionString = $Builder.ConnectionString
+        if ($Credential) { $conn.Credential = $Credential }
+        if ($RetryProvider) { $conn.RetryLogicProvider = $RetryProvider }
+        try { $conn.Open(); return $conn }
+        catch {
+            try { $conn.Dispose() } catch {}
+            # Surface the error unless a trusting retry is still allowed and untried.
+            if ($trust -or -not $AllowTrustServerCertificate) { throw }
+        }
+    }
+}
+
+function Format-ShrinkSize {
+    <# .SYNOPSIS Format a size given in MiB using an auto-selected binary unit (KiB, MiB, GiB, or TiB). #>
+    [CmdletBinding()][OutputType([string])]
+    param([Parameter(Mandatory)][double]$Megabytes)
+    if ($Megabytes -ge 1048576) { '{0:N1} TiB' -f ($Megabytes / 1048576) }
+    elseif ($Megabytes -ge 1024) { '{0:N1} GiB' -f ($Megabytes / 1024) }
+    elseif ($Megabytes -ge 1) { '{0:N1} MiB' -f $Megabytes }
+    else { '{0:N0} KiB' -f ($Megabytes * 1024) }
+}
+
+function Get-ShrinkSizeUnit {
+    <# .SYNOPSIS
+      Choose a single binary unit (KiB, MiB, GiB, or TiB) appropriate for the largest size in a
+      set, so a table can render every value in one consistent unit. Returns the unit name, the
+      number of MiB per unit, and the decimal places to use. #>
+    [CmdletBinding()][OutputType([hashtable])]
+    param([Parameter(Mandatory)][double]$MaxMegabytes)
+    if ($MaxMegabytes -ge 1048576) { @{ Name = 'TiB'; PerMB = 1048576.0; Decimals = 1 } }
+    elseif ($MaxMegabytes -ge 1024) { @{ Name = 'GiB'; PerMB = 1024.0; Decimals = 1 } }
+    elseif ($MaxMegabytes -ge 1) { @{ Name = 'MiB'; PerMB = 1.0; Decimals = 1 } }
+    else { @{ Name = 'KiB'; PerMB = (1.0 / 1024.0); Decimals = 0 } }
+}
+
+function Format-ShrinkDuration {
+    <# .SYNOPSIS Format a TimeSpan as a compact "Dd Hh Mm Ss" duration, omitting leading zero units. #>
+    [CmdletBinding()][OutputType([string])]
+    param([Parameter(Mandatory)][TimeSpan]$TimeSpan)
+    $parts = @()
+    if ($TimeSpan.Days -gt 0) { $parts += '{0}d' -f $TimeSpan.Days }
+    if ($parts.Count -gt 0 -or $TimeSpan.Hours -gt 0) { $parts += '{0}h' -f $TimeSpan.Hours }
+    if ($parts.Count -gt 0 -or $TimeSpan.Minutes -gt 0) { $parts += '{0}m' -f $TimeSpan.Minutes }
+    $parts += '{0}s' -f $TimeSpan.Seconds
+    $parts -join ' '
+}
+
+function Format-ShrinkKeyValueTable {
+    <# .SYNOPSIS Render ordered label/value pairs as aligned two-column rows (one string per row). #>
+    [CmdletBinding()][OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)][System.Collections.Specialized.OrderedDictionary]$Rows,
+        [string]$Indent = '  '
+    )
+    $width = ($Rows.Keys | Measure-Object -Property Length -Maximum).Maximum
+    foreach ($k in $Rows.Keys) { '{0}{1} : {2}' -f $Indent, ([string]$k).PadRight($width), $Rows[$k] }
+}
+
+function Format-ShrinkTable {
+    <# .SYNOPSIS
+      Render rows (each an [ordered] dictionary of column -> value) as an aligned fixed-width table
+      with a header and separator. Columns whose names are listed in -RightAlign are right-justified;
+      all others are left-justified. Returns one string per line (empty when there are no rows). #>
+    [CmdletBinding()][OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Rows,
+        [string[]]$RightAlign = @()
+    )
+    if ($Rows.Count -eq 0) { return @() }
+    $cols = @($Rows[0].Keys)
+    $width = @{}
+    foreach ($c in $cols) {
+        $m = ([string]$c).Length
+        foreach ($r in $Rows) { $len = ([string]$r[$c]).Length; if ($len -gt $m) { $m = $len } }
+        $width[$c] = $m
+    }
+    $slots = for ($i = 0; $i -lt $cols.Count; $i++) {
+        if ($cols[$i] -in $RightAlign) { "{$i,$($width[$cols[$i]])}" } else { "{$i,-$($width[$cols[$i]])}" }
+    }
+    $fmt = $slots -join '  '
+    $lines = [System.Collections.Generic.List[string]]::new()
+    $lines.Add(($fmt -f $cols))
+    $lines.Add(($fmt -f @($cols | ForEach-Object { '-' * $width[$_] })))
+    foreach ($r in $Rows) { $lines.Add(($fmt -f @($cols | ForEach-Object { [string]$r[$_] }))) }
+    $lines.ToArray()
+}
+
+function Format-ShrinkFileReport {
+    <# .SYNOPSIS
+      Render a per-file shrink-potential table (File, Name, Used, Allocated, Reclaimable),
+      sorted by reclaimable space descending and limited to the top N files. Returns one string
+      per line, with a trailing note when files are omitted. #>
+    [CmdletBinding()][OutputType([string[]])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Files,
+        [int]$TopN = 100
+    )
+    $sorted = @($Files | Sort-Object `
+            @{ Expression = { [long]$_.ReclaimableMB }; Descending = $true }, `
+            @{ Expression = { [int]$_.FileId }; Descending = $false })
+    $shown = @($sorted | Select-Object -First $TopN)
+    if ($shown.Count -eq 0) { return '(no data files found)' }
+
+    # Pick one unit for the whole table (from the largest value) so sizes are comparable and never
+    # mixed across rows; the chosen unit is shown in the column headers instead of on each cell.
+    $maxMb = 0.0
+    foreach ($f in $shown) {
+        foreach ($v in @([double]$f.AllocatedMB, [double]$f.UsedMB, [double]$f.ReclaimableMB)) {
+            if ($v -gt $maxMb) { $maxMb = $v }
+        }
+    }
+    $unit = Get-ShrinkSizeUnit -MaxMegabytes $maxMb
+    $numFmt = '{0:N' + $unit.Decimals + '}'
+    $usedHdr = "Used ($($unit.Name))"
+    $allocHdr = "Allocated ($($unit.Name))"
+    $reclHdr = "Reclaimable ($($unit.Name))"
+
+    $rows = foreach ($f in $shown) {
+        [ordered]@{
+            File      = [string]$f.FileId
+            Name      = [string]$f.Name
+            $usedHdr  = ($numFmt -f ([double]$f.UsedMB / $unit.PerMB))
+            $allocHdr = ($numFmt -f ([double]$f.AllocatedMB / $unit.PerMB))
+            $reclHdr  = ($numFmt -f ([double]$f.ReclaimableMB / $unit.PerMB))
+            Eligible  = if ($f.IsEligible) { 'Yes' } else { 'No' }
+        }
+    }
+    $lines = [System.Collections.Generic.List[string]]::new()
+    Format-ShrinkTable -Rows @($rows) -RightAlign @('File', $usedHdr, $allocHdr, $reclHdr) |
+        ForEach-Object { $lines.Add($_) }
+    $omitted = $sorted.Count - $shown.Count
+    if ($omitted -gt 0) {
+        $lines.Add(("... {0} other file(s) omitted; showing the top {1} by reclaimable space." -f $omitted, $TopN))
+    }
+    $lines.ToArray()
+}
+
+function Get-ShrinkSumMB {
+    <# .SYNOPSIS Sum a numeric property over a (possibly empty) set of items, returning 0 when empty. #>
+    [CmdletBinding()][OutputType([long])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Items,
+        [Parameter(Mandatory)][string]$Property
+    )
+    $m = $Items | Measure-Object -Property $Property -Sum
+    [long]$(if ($m) { $m.Sum } else { 0 })
+}
+
+function Get-ShrinkEffectiveFloorMB {
+    <# .SYNOPSIS The size (MiB) a file will not shrink below: the larger of its used pages and any target floor. #>
+    [CmdletBinding()][OutputType([long])]
+    param(
+        [Parameter(Mandatory)][long]$UsedMB,
+        [Nullable[long]]$FloorMB = $null
+    )
+    [Math]::Max($UsedMB, $(if ($null -ne $FloorMB) { [long]$FloorMB } else { [long]0 }))
+}
+
+function Test-ShrinkWorthwhile {
+    <# .SYNOPSIS
+      True if at least MinReclaimMB of space can be reclaimed from the file - that is, the unused space
+      above its effective floor (the larger of its used pages and any target floor). #>
+    [CmdletBinding()][OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][long]$AllocatedMB,
+        [Parameter(Mandatory)][long]$UsedMB,
+        [Nullable[long]]$FloorMB = $null,
+        [long]$MinReclaimMB = 100
+    )
+    if ($AllocatedMB -le 0) { return $false }
+    ($AllocatedMB - (Get-ShrinkEffectiveFloorMB -UsedMB $UsedMB -FloorMB $FloorMB)) -ge $MinReclaimMB
+}
+
+function Get-ShrinkReclaimableMB {
+    <# .SYNOPSIS
+      Space (MiB) that could be reclaimed from a file: allocated minus its effective floor
+      (the larger of its used pages and any target floor), never negative. #>
+    [CmdletBinding()][OutputType([long])]
+    param(
+        [Parameter(Mandatory)][long]$AllocatedMB,
+        [Parameter(Mandatory)][long]$UsedMB,
+        [Nullable[long]]$FloorMB = $null
+    )
+    [long][Math]::Max(0, $AllocatedMB - (Get-ShrinkEffectiveFloorMB -UsedMB $UsedMB -FloorMB $FloorMB))
+}
+
+function Get-ShrinkBucketCounts {
+    <# .SYNOPSIS Tally completed-file outcomes (bucket names) into the reporting counts. #>
+    [CmdletBinding()][OutputType([pscustomobject])]
+    param([Parameter(Mandatory)][AllowEmptyCollection()][string[]]$Buckets)
+    [pscustomobject]@{
+        Shrunk          = @($Buckets | Where-Object { $_ -eq 'Shrunk' }).Count
+        Repacked        = @($Buckets | Where-Object { $_ -eq 'Repacked' }).Count
+        PartlyShrunk    = @($Buckets | Where-Object { $_ -eq 'PartlyShrunk' }).Count
+        AlreadyMinimal  = @($Buckets | Where-Object { $_ -eq 'AlreadyMinimal' }).Count
+        AlreadyAtTarget = @($Buckets | Where-Object { $_ -eq 'AlreadyAtTarget' }).Count
+        Grew            = @($Buckets | Where-Object { $_ -eq 'Grew' }).Count
+        GaveUp          = @($Buckets | Where-Object { $_ -eq 'GaveUp' }).Count
+        Interrupted     = @($Buckets | Where-Object { $_ -eq 'Interrupted' }).Count
+        NotProcessed    = @($Buckets | Where-Object { $_ -eq 'NotProcessed' }).Count
+    }
+}
+
+function Get-ShrinkTotalsRows {
+    <# .SYNOPSIS Build the ordered label/value rows shared by the database-total and final-summary tables. #>
+    [CmdletBinding()][OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)][string]$RunTime,
+        [Parameter(Mandatory)][string]$Used,
+        [Parameter(Mandatory)][string]$Allocated,
+        [Parameter(Mandatory)][pscustomobject]$Counts
+    )
+    [ordered]@{
+        'Run time'           = $RunTime
+        'Used'               = $Used
+        'Allocated'          = $Allocated
+        'Shrunk'             = $Counts.Shrunk
+        'Repacked'           = $Counts.Repacked
+        'Partly shrunk'      = $Counts.PartlyShrunk
+        'Already at minimum' = $Counts.AlreadyMinimal
+        'Already at target'  = $Counts.AlreadyAtTarget
+        'Grew'               = $Counts.Grew
+        'Gave up'            = $Counts.GaveUp
+        'Interrupted'        = $Counts.Interrupted
+        'Not processed'      = $Counts.NotProcessed
+    }
+}
+
+function Get-ShrinkGaveUpBucket {
+    <# .SYNOPSIS
+      Classify a give-up outcome by the net change in allocated size since the worker took
+      the file: PartlyShrunk (ended smaller), Grew (ended larger, e.g. other sessions added
+      data faster than shrink could reclaim), or GaveUp (allocated size unchanged). #>
+    [CmdletBinding()][OutputType([string])]
+    param(
+        [Parameter(Mandatory)][long]$StartAllocMB,
+        [Parameter(Mandatory)][long]$FinalAllocMB
+    )
+    if ($FinalAllocMB -lt $StartAllocMB) { 'PartlyShrunk' }
+    elseif ($FinalAllocMB -gt $StartAllocMB) { 'Grew' }
+    else { 'GaveUp' }
+}
+
+function Get-ShrinkStopOutcome {
+    <# .SYNOPSIS
+      Classify a file's outcome when the run is stopped before the file finished. A forced quit
+      (second Ctrl+C) is always Interrupted; otherwise the file is judged by its re-measured size:
+      smaller than it started -> PartlyShrunk, larger -> Grew, unchanged -> Interrupted (no progress).
+      StartAllocMB null (never measured) or FinalAllocMB null (could not re-measure) -> Interrupted.
+      Pure/side-effect-free so the two-stage Ctrl+C and run-time-limit classification is unit-testable. #>
+    [CmdletBinding()][OutputType([pscustomobject])]
+    param(
+        [Nullable[long]]$StartAllocMB,
+        [Nullable[long]]$FinalAllocMB,
+        [ValidateSet('Timeout', 'Ctrl+C')][string]$Cause = 'Ctrl+C',
+        [switch]$Force
+    )
+    $causeText = if ($Cause -eq 'Timeout') { 'run time limit reached' } else { 'stopped early (Ctrl+C)' }
+    if ($Force) {
+        return [pscustomobject]@{ Bucket = 'Interrupted'; Reason = 'stopped immediately (Ctrl+C pressed twice); the final size was not measured' }
+    }
+    if ($null -eq $StartAllocMB) {
+        return [pscustomobject]@{ Bucket = 'Interrupted'; Reason = "$causeText while this file was being shrunk" }
+    }
+    if ($null -eq $FinalAllocMB) {
+        return [pscustomobject]@{ Bucket = 'Interrupted'; Reason = "$causeText; the final size could not be measured" }
+    }
+    if ([long]$FinalAllocMB -lt [long]$StartAllocMB) {
+        return [pscustomobject]@{ Bucket = 'PartlyShrunk'; Reason = "$causeText; reduced from $(Format-ShrinkSize $StartAllocMB) to $(Format-ShrinkSize $FinalAllocMB)" }
+    }
+    if ([long]$FinalAllocMB -gt [long]$StartAllocMB) {
+        return [pscustomobject]@{ Bucket = 'Grew'; Reason = "$causeText; grew from $(Format-ShrinkSize $StartAllocMB) to $(Format-ShrinkSize $FinalAllocMB) (other workloads adding data)" }
+    }
+    return [pscustomobject]@{ Bucket = 'Interrupted'; Reason = "$causeText before this file made measurable progress" }
+}
+
+function Test-ShrinkParameterSet {
+    <# .SYNOPSIS Validate a parameter set; returns an array of error strings (empty = valid). #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param([Parameter(Mandatory)][hashtable]$Params)
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+    if ($Params['TruncateOnly'] -and $Params['NoTruncate']) {
+        $errors.Add('TruncateOnly and NoTruncate cannot both be set (mutually exclusive).')
+    }
+    if ($Params['TruncateOnly'] -and $null -ne $Params['FileTargetSizeGiB']) {
+        $errors.Add('FileTargetSizeGiB is not compatible with TruncateOnly (truncate-only does no data movement).')
+    }
+    if ($Params['AuthType'] -eq 'SQL') {
+        if ([string]::IsNullOrWhiteSpace([string]$Params['SqlLogin'])) {
+            $errors.Add('SqlLogin is required for SQL authentication.')
+        }
+        $pw = $Params['SqlPassword']
+        if ($pw -and $pw -isnot [securestring]) {
+            $errors.Add("SqlPassword must be a SecureString, not plain text. Create one with: `$pw = Read-Host -AsSecureString 'SQL password'; then pass -SqlPassword `$pw.")
+        }
+    }
+    if ($Params['AuthType'] -notin @('EntraID', 'Windows', 'SQL')) {
+        $errors.Add("Invalid AuthType '$($Params['AuthType'])' (expected EntraID, Windows, or SQL).")
+    }
+    if ($Params['AbortAfterWait'] -notin @('SELF', 'BLOCKERS')) {
+        $errors.Add("Invalid AbortAfterWait '$($Params['AbortAfterWait'])' (expected SELF or BLOCKERS).")
+    }
+    , $errors.ToArray()
+}
+
+function Resolve-ShrinkLogPath {
+    <# .SYNOPSIS
+      Resolve a log file path to a full path and confirm its directory exists and the file is
+      writable, creating the (empty) file if needed. Throws a clear error if the path is invalid,
+      its directory is missing, the path is a directory, or it cannot be written. #>
+    [CmdletBinding()][OutputType([string])]
+    param([Parameter(Mandatory)][string]$Path)
+
+    # Resolve relative paths against the caller's PowerShell location ($PWD).
+    try { $full = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path) }
+    catch { throw "LogPath '$Path' is not a valid path: $($_.Exception.Message)" }
+
+    $dir = [System.IO.Path]::GetDirectoryName($full)
+    if (-not (Test-Path -LiteralPath $dir -PathType Container)) {
+        throw "LogPath directory '$dir' does not exist. Create it or choose a different -LogPath."
+    }
+    if (Test-Path -LiteralPath $full -PathType Container) {
+        throw "LogPath '$full' is a directory. Specify a file path for -LogPath."
+    }
+    try {
+        $fs = [System.IO.File]::Open($full, [System.IO.FileMode]::Append, [System.IO.FileAccess]::Write, [System.IO.FileShare]::ReadWrite)
+        $fs.Dispose()
+    } catch {
+        throw "LogPath '$full' is not writable: $($_.Exception.Message)"
+    }
+    $full
+}
+
+function Get-ShrinkBackoffSeconds {
+    <# .SYNOPSIS Exponential backoff with full jitter: uniform(0 .. min(Cap, Base*2^Attempt)). #>
+    [CmdletBinding()][OutputType([double])]
+    param(
+        [Parameter(Mandatory)][int]$Attempt,
+        [int]$BaseSec = 5,
+        [int]$CapSec = 60,
+        [System.Random]$Random
+    )
+    if (-not $Random) { $Random = [System.Random]::new() }
+    $exp = [double]$BaseSec * [Math]::Pow(2, [Math]::Max(0, $Attempt))
+    $cap = [Math]::Min([double]$CapSec, $exp)
+    [Math]::Round($Random.NextDouble() * $cap, 2)
+}
+
+function Get-ShrinkNextTargetMB {
+    <# .SYNOPSIS Next SHRINKFILE target (MB): one step below the current size, clamped to the floor and
+       to a minimum of 1 (DBCC reads a target of 0 as "shrink to the file's creation size"). #>
+    [CmdletBinding()][OutputType([long])]
+    param(
+        [Parameter(Mandatory)][long]$AllocatedMB,
+        [Nullable[long]]$FloorMB = $null,
+        [long]$StepMB = 20480
+    )
+    $floor = if ($null -ne $FloorMB) { [long]$FloorMB } else { [long]0 }
+    $next = $AllocatedMB - $StepMB
+    if ($next -lt $floor) { $next = $floor }
+    # DBCC SHRINKFILE treats a target_size of 0 as "shrink to the file's creation size", which leaves
+    # unused space unreclaimed (a file created at, say, 10 GiB never shrinks below 10 GiB). Never target
+    # 0: 1 MB shrinks to the actual used-data size (SQL will not shrink a file past its used pages).
+    if ($next -lt 1) { $next = 1 }
+    [long]$next
+}
+
+function Select-ShrinkNextFile {
+    <#
+    .SYNOPSIS
+      Pick the next file to shrink: the one with the most reclaimable space above its
+      floor, skipping files already being shrunk by another session and files that have
+      already reached a terminal state this run.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][object[]]$Files,
+        [int[]]$OwnedFileIds = @(),
+        [int[]]$ExcludedFileIds = @()
+    )
+    $cand = foreach ($f in $Files) {
+        if ($f.FileId -in $OwnedFileIds) { continue }
+        if ($f.FileId -in $ExcludedFileIds) { continue }
+        if (([long]$f.AllocatedMB - [long]$f.UsedMB) -le 0) { continue }
+        $floor = if ($null -ne $f.FloorMB) { [long]$f.FloorMB } else { [long]0 }
+        if ([long]$f.AllocatedMB -le $floor) { continue }
+        $f
+    }
+    if (-not $cand) { return $null }
+    $cand |
+        Sort-Object `
+            @{ Expression = { Get-ShrinkReclaimableMB -AllocatedMB ([long]$_.AllocatedMB) -UsedMB ([long]$_.UsedMB) -FloorMB $_.FloorMB }; Descending = $true }, `
+            @{ Expression = { [int]$_.FileId }; Descending = $false } |
+        Select-Object -First 1
+}
+
+function Get-ShrinkDeltaWithReset {
+    <# .SYNOPSIS Non-negative delta, detecting a counter reset (Current < Previous => skip). #>
+    [CmdletBinding()]
+    param([Parameter(Mandatory)][long]$Previous, [Parameter(Mandatory)][long]$Current)
+    if ($Current -lt $Previous) {
+        [pscustomobject]@{ IsReset = $true; Delta = $null }
+    } else {
+        [pscustomobject]@{ IsReset = $false; Delta = [long]($Current - $Previous) }
+    }
+}
+
+function Update-ShrinkStuckState {
+    <# .SYNOPSIS Update per-session stuck state. A worker is stuck when, for at least WindowSec, EITHER
+       the same non-zero blocking session has persisted, OR neither CPU nor reads have advanced. #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][hashtable]$State,
+        [int]$Blocker = 0,
+        [long]$Cpu = 0,
+        [long]$Reads = 0,
+        [datetime]$Now = (Get-Date),
+        [int]$WindowSec = 300
+    )
+    # Blocker streak: how long the same non-zero blocking session has persisted. Cleared when there is
+    # no blocker; restarted when the blocking session changes.
+    if (-not $Blocker) {
+        $State.BlockerSince = $null
+    }
+    elseif ($State.Blocker -ne $Blocker -or $null -eq $State.BlockerSince) {
+        $State.BlockerSince = $Now
+    }
+    # No-progress streak: how long neither CPU nor reads have changed. Any change - including a
+    # per-request counter reset, which signals a new step - counts as progress and restarts the streak.
+    if ($State.Cpu -ne $Cpu -or $State.Reads -ne $Reads -or $null -eq $State.NoProgressSince) {
+        $State.NoProgressSince = $Now
+    }
+
+    $blockerStuck = ($null -ne $State.BlockerSince) -and (($Now - [datetime]$State.BlockerSince).TotalSeconds -ge $WindowSec)
+    $noProgressStuck = ($null -ne $State.NoProgressSince) -and (($Now - [datetime]$State.NoProgressSince).TotalSeconds -ge $WindowSec)
+    $isStuck = [bool]($blockerStuck -or $noProgressStuck)
+
+    $State.Blocker = $Blocker
+    $State.Cpu = $Cpu
+    $State.Reads = $Reads
+    [pscustomobject]@{ IsStuck = $isStuck; BlockerStuck = [bool]$blockerStuck; NoProgressStuck = [bool]$noProgressStuck }
+}
+
+function New-ShrinkCommandText {
+    <# .SYNOPSIS Build the DBCC SHRINKFILE T-SQL for one file. #>
+    [CmdletBinding()][OutputType([string])]
+    param(
+        [Parameter(Mandatory)][int]$FileId,
+        [Nullable[long]]$TargetMB = $null,
+        [switch]$TruncateOnly,
+        [switch]$NoTruncate,
+        [switch]$WaitAtLowPriority,
+        [ValidateSet('SELF', 'BLOCKERS')][string]$AbortAfterWait = 'SELF'
+    )
+    if ($TruncateOnly -and $NoTruncate) { throw 'TruncateOnly and NoTruncate are mutually exclusive.' }
+    $inner =
+        if ($TruncateOnly) { "$FileId, TRUNCATEONLY" }
+        elseif ($null -ne $TargetMB) {
+            if ($NoTruncate) { "$FileId, $TargetMB, NOTRUNCATE" } else { "$FileId, $TargetMB" }
+        }
+        else { "$FileId" }
+    $withParts = [System.Collections.Generic.List[string]]::new()
+    if ($WaitAtLowPriority) { $withParts.Add("WAIT_AT_LOW_PRIORITY (ABORT_AFTER_WAIT = $AbortAfterWait)") }
+    $withParts.Add('NO_INFOMSGS')
+    "DBCC SHRINKFILE ($inner) WITH $($withParts -join ', ')"
+}
diff --git a/samples/features/shrink/shrink-driver/tests/README.md b/samples/features/shrink/shrink-driver/tests/README.md
new file mode 100644
index 0000000000..cb8f888c1d
--- /dev/null
+++ b/samples/features/shrink/shrink-driver/tests/README.md
@@ -0,0 +1,101 @@
+# ShrinkDriver tests
+
+The script is covered by two kinds of tests, both written with
+[Pester](https://pester.dev) (the standard PowerShell test framework), version 5 or later:
+
+- **Unit tests** — exercise the pure helper functions in isolation. Fast, and need **no database**.
+- **Integration tests** — run real `DBCC SHRINKFILE` operations against a **live SQL instance**, so
+  they validate the script's actual behavior end to end.
+
+## Test files
+
+| File | What it is |
+| --- | --- |
+| `ShrinkDriver.Unit.Tests.ps1` | Unit tests for the helper functions. |
+| `ShrinkDriver.Integration.Tests.ps1` | Integration tests that create a small throwaway database, run real shrinks, and drop it. |
+| `fixtures/ShrinkTestDb.psm1` | Helpers used by the integration tests to build and tear down the test database. Not a test file itself. |
+
+## Prerequisites
+
+- **PowerShell 7 or later.**
+- **Pester 5 or later.** Install it once (per user):
+
+  ```powershell
+  Install-Module Pester -MinimumVersion 5.0 -Scope CurrentUser
+  ```
+
+- **For the integration tests only:** the `SqlServer` module and a reachable SQL instance.
+
+  ```powershell
+  Install-Module SqlServer -Scope CurrentUser
+  ```
+
+  By default the integration tests use **SQL Server LocalDB** (installed with most SQL Server tooling),
+  so no extra setup is needed to run them locally.
+
+> Run all the commands below from the **sample root** — the folder that contains the `src` and `tests`
+> directories.
+
+## Run the unit tests (fast, no database)
+
+```powershell
+Invoke-Pester -Path .\tests\ShrinkDriver.Unit.Tests.ps1
+```
+
+Pester prints one line per test (`[+]` passed, `[-]` failed) and a summary such as
+`Tests Passed: 106, Failed: 0`. **Every change to `src\ShrinkDriver.ps1` should keep these green.**
+
+## Run the integration tests
+
+Against the default local instance (SQL Server LocalDB, Windows auth):
+
+```powershell
+Invoke-Pester -Path .\tests\ShrinkDriver.Integration.Tests.ps1 -Tag Integration
+```
+
+These create small throwaway databases, run real shrinks, and drop them afterward. They are **skipped
+automatically when no SQL instance is reachable**, and individual tests that don't apply to the target
+instance are skipped as well — so a run may report some `Skipped` tests, which is expected.
+
+To target a different instance (for example, a database on an Azure SQL Database logical server), set these
+environment variables before running, then clear them afterward:
+
+```powershell
+$env:SHRINKDRIVER_TEST_SERVER = 'myserver.database.windows.net'
+$env:SHRINKDRIVER_TEST_AUTH   = 'EntraID'      # EntraID | Windows | SQL
+# For SQL authentication, also set the login; the password is requested securely when the tests run:
+# $env:SHRINKDRIVER_TEST_LOGIN = 'appuser'
+# Only for an instance with a self-signed certificate if you trust the connection:
+# $env:SHRINKDRIVER_TEST_TRUSTCERT = '1'
+
+Invoke-Pester -Path .\tests\ShrinkDriver.Integration.Tests.ps1 -Tag Integration
+
+Remove-Item Env:\SHRINKDRIVER_TEST_SERVER, Env:\SHRINKDRIVER_TEST_AUTH -ErrorAction SilentlyContinue
+```
+
+## Run everything, or just the fast gate
+
+Run every test in the folder:
+
+```powershell
+Invoke-Pester -Path .\tests
+```
+
+Run only the fast unit gate (skip the integration tests):
+
+```powershell
+Invoke-Pester -Path .\tests -ExcludeTag Integration
+```
+
+## Validating a change to the script
+
+After editing `src\ShrinkDriver.ps1`:
+
+1. **Run the unit tests** and confirm they all pass — this catches most regressions quickly.
+2. **Run the integration tests** (against LocalDB, or another instance via the variables above) to
+   confirm the real shrink behavior still works.
+3. If something fails, re-run with `-Output Detailed` to see each test and the failing assertion:
+
+   ```powershell
+   Invoke-Pester -Path .\tests\ShrinkDriver.Unit.Tests.ps1 -Output Detailed
+   ```
diff --git a/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1 b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1
new file mode 100644
index 0000000000..d71c0935e5
--- /dev/null
+++ b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1
@@ -0,0 +1,339 @@
+#requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+<#
+  Integration tests for ShrinkDriver. These run real DBCC SHRINKFILE operations against a live SQL
+  instance. By default they use SQL Server LocalDB (Windows auth); set $env:SHRINKDRIVER_TEST_SERVER
+  (+ optionally _AUTH = EntraID|Windows|SQL, _LOGIN, _PASSWORD, and _TRUSTCERT=1 for a self-signed dev
+  instance) to target another instance, e.g. an Azure SQL Database logical server. They are skipped
+  automatically when no instance is reachable, so they never break the unit test gate.
+
+  Run:  Invoke-Pester -Path .\tests\ShrinkDriver.Integration.Tests.ps1 -Tag Integration
+
+  Notes:
+  - Small files are used so the suite runs quickly.
+  - DROP-created free space appears only after deferred deallocation settles (handled
+    by Wait-ShrinkFreeSpaceSettled).
+  - Shrinks assert on the returned result object and use -BackoffBaseSeconds/-BackoffCapSeconds 0
+    for instant retries. Most contexts pass -WaitAtLowPriority:$false so an (optionally blocked)
+    shrink resolves immediately instead of waiting at low priority; WAIT_AT_LOW_PRIORITY itself is
+    exercised by its own context.
+#>
+
+BeforeDiscovery {
+    Import-Module (Join-Path $PSScriptRoot 'fixtures\ShrinkTestDb.psm1') -Force
+    $server = Get-ShrinkTestServer
+    # Box SQL Server / LocalDB vs Azure SQL Database (EngineEdition 5, which provisions a single data
+    # file). Some contexts apply only to the box engine and are skipped otherwise.
+    $isBoxEngine = $false
+    if ($server) {
+        try { $isBoxEngine = (Get-ShrinkTestEngineEdition -Context $server) -ne 5 } catch { $isBoxEngine = $false }
+    }
+}
+
+Describe 'ShrinkDriver integration' -Tag 'Integration' -Skip:(-not $server) {
+
+    BeforeAll {
+        Import-Module (Join-Path $PSScriptRoot 'fixtures\ShrinkTestDb.psm1') -Force
+        . (Join-Path $PSScriptRoot '..\src\ShrinkDriver.ps1')
+        $server = Get-ShrinkTestServer
+        $log = Join-Path ([System.IO.Path]::GetTempPath()) 'shrinkdriver-integration.log'
+        # A dev SQL Server with a self-signed certificate needs its certificate trusted; opt in for such
+        # a target via $env:SHRINKDRIVER_TEST_TRUSTCERT. Instances with a valid or client-trusted
+        # certificate (Azure SQL, LocalDB) are validated normally, so nothing is forced for them.
+        if ($server.TrustServerCertificate) {
+            $PSDefaultParameterValues['Invoke-ShrinkDriver:TrustServerCertificate'] = $true
+        }
+    }
+
+    Context 'Report mode' {
+        BeforeAll { $db = New-ShrinkTestDatabase -Context $server }
+        AfterAll { Remove-ShrinkTestDatabase -TestDb $db }
+
+        It 'returns a Report result listing eligible files' {
+            $r = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Report `
+                -AuthType $server.Auth -MinReclaimMBOverride 1 -PassThru -LogPath $log 6>$null
+            $r.Mode | Should -Be 'Report'
+            $r.Files.Count | Should -BeGreaterThan 0
+            $r.Eligible | Should -BeGreaterThan 0
+            @($r.Files | Where-Object IsEligible).Count | Should -Be $r.Eligible
+        }
+
+        It 'reports zero eligible when the threshold is huge (no crash)' {
+            $r = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Report `
+                -AuthType $server.Auth -MinReclaimMBOverride 1000000000 -PassThru -LogPath $log 6>$null
+            $r.Mode | Should -Be 'Report'
+            $r.Eligible | Should -Be 0
+        }
+    }
+
+    Context 'Shrink happy path' {
+        BeforeAll {
+            $db = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $db -MinFreeMB 8 | Out-Null
+            $allocBefore = (Get-ShrinkTestFileSizes -TestDb $db | Measure-Object -Property alloc_mb -Sum).Sum
+            $res = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Shrink `
+                -AuthType $server.Auth -WaitAtLowPriority:$false -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                -MinReclaimMBOverride 1 -StepMBOverride 20 -Sessions 4 -StatusIntervalSeconds 5 -PassThru -LogPath $log 6>$null
+        }
+        AfterAll { Remove-ShrinkTestDatabase -TestDb $db }
+
+        It 'returns a Shrink result object' {
+            $res.Mode | Should -Be 'Shrink'
+            $res.Files.Count | Should -BeGreaterThan 0
+        }
+
+        It 'classifies every file into a known bucket' {
+            $known = @('Shrunk', 'PartlyShrunk', 'AlreadyMinimal', 'AlreadyAtTarget', 'Repacked', 'Grew', 'GaveUp', 'Interrupted', 'NotProcessed')
+            foreach ($f in $res.Files) { $f.Bucket | Should -BeIn $known }
+        }
+
+        It 'reclaims space from at least one file' {
+            ($res.Counts.Shrunk + $res.Counts.PartlyShrunk) | Should -BeGreaterThan 0
+        }
+
+        It 'reduces the total allocated size' {
+            $allocAfter = (Get-ShrinkTestFileSizes -TestDb $db | Measure-Object -Property alloc_mb -Sum).Sum
+            $allocAfter | Should -BeLessThan $allocBefore
+        }
+    }
+
+    Context 'WAIT_AT_LOW_PRIORITY (low-priority lock)' {
+        # These runs are uncontended, so the low-priority lock is granted at once and the driver's emitted
+        # WAIT_AT_LOW_PRIORITY (ABORT_AFTER_WAIT = ...) clause is exercised end-to-end for both
+        # abort choices.
+        BeforeAll {
+            $known = @('Shrunk', 'PartlyShrunk', 'AlreadyMinimal', 'AlreadyAtTarget', 'Repacked', 'Grew', 'GaveUp', 'Interrupted', 'NotProcessed')
+
+            $dbSelf = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $dbSelf -MinFreeMB 8 | Out-Null
+            $allocBeforeSelf = (Get-ShrinkTestFileSizes -TestDb $dbSelf | Measure-Object -Property alloc_mb -Sum).Sum
+            $resSelf = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $dbSelf.Database -Mode Shrink `
+                -AuthType $server.Auth -WaitAtLowPriority:$true -AbortAfterWait SELF -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                -MinReclaimMBOverride 1 -StepMBOverride 20 -Sessions 4 -StatusIntervalSeconds 5 -PassThru -LogPath $log 6>$null
+            $allocAfterSelf = (Get-ShrinkTestFileSizes -TestDb $dbSelf | Measure-Object -Property alloc_mb -Sum).Sum
+
+            $dbBlockers = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $dbBlockers -MinFreeMB 8 | Out-Null
+            $allocBeforeBlockers = (Get-ShrinkTestFileSizes -TestDb $dbBlockers | Measure-Object -Property alloc_mb -Sum).Sum
+            $resBlockers = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $dbBlockers.Database -Mode Shrink `
+                -AuthType $server.Auth -WaitAtLowPriority:$true -AbortAfterWait BLOCKERS -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                -MinReclaimMBOverride 1 -StepMBOverride 20 -Sessions 4 -StatusIntervalSeconds 5 -PassThru -LogPath $log 6>$null
+            $allocAfterBlockers = (Get-ShrinkTestFileSizes -TestDb $dbBlockers | Measure-Object -Property alloc_mb -Sum).Sum
+        }
+        AfterAll {
+            Remove-ShrinkTestDatabase -TestDb $dbSelf
+            Remove-ShrinkTestDatabase -TestDb $dbBlockers
+        }
+
+        It 'reclaims space with ABORT_AFTER_WAIT = SELF' {
+            ($resSelf.Counts.Shrunk + $resSelf.Counts.PartlyShrunk) | Should -BeGreaterThan 0
+            $allocAfterSelf | Should -BeLessThan $allocBeforeSelf
+        }
+
+        It 'reclaims space with ABORT_AFTER_WAIT = BLOCKERS' {
+            ($resBlockers.Counts.Shrunk + $resBlockers.Counts.PartlyShrunk) | Should -BeGreaterThan 0
+            $allocAfterBlockers | Should -BeLessThan $allocBeforeBlockers
+        }
+
+        It 'classifies every file into a known bucket under low-priority waits' {
+            $resSelf.Files.Count | Should -BeGreaterThan 0
+            $resBlockers.Files.Count | Should -BeGreaterThan 0
+            foreach ($f in $resSelf.Files) { $f.Bucket | Should -BeIn $known }
+            foreach ($f in $resBlockers.Files) { $f.Bucket | Should -BeIn $known }
+        }
+    }
+
+    Context 'Per-file floor (FileTargetMBOverride)' {
+        BeforeAll {
+            $db = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $db -MinFreeMB 8 | Out-Null
+            $before = Get-ShrinkTestFileSizes -TestDb $db
+            $allocBefore = ($before | Measure-Object -Property alloc_mb -Sum).Sum
+            $beforeAllocById = @{}
+            $before | ForEach-Object { $beforeAllocById[[int]$_.file_id] = [int]$_.alloc_mb }
+            $maxUsed = ($before | Measure-Object -Property used_mb -Maximum).Maximum
+            $floor = [int]$maxUsed + 5   # above every file's used
+            $res = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Shrink `
+                -AuthType $server.Auth -WaitAtLowPriority:$false -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                -MinReclaimMBOverride 1 -FileTargetMBOverride $floor -StepMBOverride 10 -Sessions 4 `
+                -StatusIntervalSeconds 5 -PassThru -LogPath $log 6>$null
+        }
+        AfterAll { Remove-ShrinkTestDatabase -TestDb $db }
+
+        It 'never shrinks a file below the floor' {
+            # A file that started above the floor must be held at or above it. Files already smaller than
+            # the floor are left untouched (and may legitimately sit below it), so they are excluded.
+            foreach ($f in (Get-ShrinkTestFileSizes -TestDb $db)) {
+                if ($beforeAllocById[[int]$f.file_id] -gt $floor) { $f.alloc_mb | Should -BeGreaterOrEqual $floor }
+            }
+        }
+
+        It 'reduces total allocated size toward the floor' {
+            $allocAfter = (Get-ShrinkTestFileSizes -TestDb $db | Measure-Object -Property alloc_mb -Sum).Sum
+            $allocAfter | Should -BeLessThan $allocBefore
+        }
+    }
+
+    Context 'NoTruncate (repack only)' {
+        BeforeAll {
+            $db = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $db -MinFreeMB 8 | Out-Null
+            $allocBefore = (Get-ShrinkTestFileSizes -TestDb $db | Measure-Object -Property alloc_mb -Sum).Sum
+            $res = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Shrink `
+                -AuthType $server.Auth -NoTruncate -WaitAtLowPriority:$false -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                -MinReclaimMBOverride 1 -Sessions 4 -StatusIntervalSeconds 5 -PassThru -LogPath $log 6>$null
+        }
+        AfterAll { Remove-ShrinkTestDatabase -TestDb $db }
+
+        It 'reports every processed file as Repacked' {
+            $res.Files.Count | Should -BeGreaterThan 0
+            $res.Counts.Repacked | Should -Be $res.Files.Count
+        }
+
+        It 'never releases space (nothing shrunk)' {
+            ($res.Counts.Shrunk + $res.Counts.PartlyShrunk) | Should -Be 0
+        }
+
+        It 'leaves the total allocated size unchanged' {
+            $allocAfter = (Get-ShrinkTestFileSizes -TestDb $db | Measure-Object -Property alloc_mb -Sum).Sum
+            $allocAfter | Should -Be $allocBefore
+        }
+    }
+
+    Context 'TruncateOnly (release tail free space)' -Skip:(-not $isBoxEngine) {
+        BeforeAll {
+            $db = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $db -MinFreeMB 8 | Out-Null
+            # Grow every data file so there is guaranteed unused space at the tail for TRUNCATEONLY to
+            # reclaim (the drop-created free space is interspersed and may not sit at the file end).
+            Add-ShrinkTestTailSpace -TestDb $db -AddMB 48
+            $allocBefore = (Get-ShrinkTestFileSizes -TestDb $db | Measure-Object -Property alloc_mb -Sum).Sum
+            $res = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Shrink `
+                -AuthType $server.Auth -TruncateOnly -WaitAtLowPriority:$false -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                -MinReclaimMBOverride 1 -Sessions 4 -StatusIntervalSeconds 5 -PassThru -LogPath $log 6>$null
+        }
+        AfterAll { Remove-ShrinkTestDatabase -TestDb $db }
+
+        It 'classifies every file into a known bucket' {
+            $known = @('Shrunk', 'PartlyShrunk', 'AlreadyMinimal', 'AlreadyAtTarget', 'Repacked', 'Grew', 'GaveUp', 'Interrupted', 'NotProcessed')
+            $res.Files.Count | Should -BeGreaterThan 0
+            foreach ($f in $res.Files) { $f.Bucket | Should -BeIn $known }
+        }
+
+        It 'reclaims the trailing free space' {
+            $res.Counts.Shrunk | Should -BeGreaterThan 0
+            $allocAfter = (Get-ShrinkTestFileSizes -TestDb $db | Measure-Object -Property alloc_mb -Sum).Sum
+            $allocAfter | Should -BeLessThan $allocBefore
+        }
+    }
+
+    Context 'Graceful stop on the run-time limit' {
+        BeforeAll {
+            $db = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $db -MinFreeMB 8 | Out-Null
+            # Hold an exclusive lock on a table the fixture keeps (it drops every other one) so the
+            # shrink must move that table's pages and blocks; the run then cannot finish and must stop
+            # when the short run-time limit fires.
+            $blocker = Open-ShrinkTestBlocker -TestDb $db -TableName 'dbo.t2'
+            try {
+                $res = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Shrink `
+                    -AuthType $server.Auth -WaitAtLowPriority:$false -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                    -MinReclaimMBOverride 1 -StepMBOverride 10 -Sessions 2 -StatusIntervalSeconds 2 `
+                    -MaxRuntimeSecondsOverride 5 -PassThru -LogPath $log 6>$null
+            }
+            finally {
+                Close-ShrinkTestBlocker -Connection $blocker
+            }
+        }
+        AfterAll { Remove-ShrinkTestDatabase -TestDb $db }
+
+        It 'stops because of the run-time limit' {
+            $res.StoppedBy | Should -Be 'Timeout'
+        }
+
+        It 'records in-flight or unprocessed files instead of dropping them' {
+            $res.Files.Count | Should -BeGreaterThan 0
+            ($res.Counts.Interrupted + $res.Counts.PartlyShrunk + $res.Counts.NotProcessed) | Should -BeGreaterThan 0
+        }
+    }
+
+    Context 'Worker reconnect after a dropped connection' -Skip:(-not $isBoxEngine) {
+        BeforeAll {
+            $db = New-ShrinkTestDatabase -Context $server
+            Wait-ShrinkFreeSpaceSettled -TestDb $db -MinFreeMB 8 | Out-Null
+            $rlog = Join-Path ([System.IO.Path]::GetTempPath()) ("shrinkdriver-reconnect-{0}.log" -f [guid]::NewGuid().ToString('N'))
+            # Block the shrink with an exclusive lock on a table the fixture keeps (it drops every other
+            # one) so the worker sessions stay connected, then kill one from a background job to force
+            # the driver's reconnect path. A short run-time limit ends the (blocked) run.
+            $blocker = Open-ShrinkTestBlocker -TestDb $db -TableName 'dbo.t2'
+            $killJob = Start-Job -ScriptBlock {
+                param($serverInstance, $database)
+                Import-Module SqlServer -ErrorAction Stop
+                $kills = 0
+                $deadline = (Get-Date).AddSeconds(30)
+                while ((Get-Date) -lt $deadline -and $kills -lt 2) {
+                    try {
+                        $r = Invoke-Sqlcmd -ServerInstance $serverInstance -Database $database -TrustServerCertificate -ErrorAction Stop `
+                            -Query "SELECT TOP (1) session_id AS spid FROM sys.dm_exec_sessions WHERE program_name LIKE 'ShrinkDriver-w%'"
+                        if ($r -and $null -ne $r.spid) {
+                            Invoke-Sqlcmd -ServerInstance $serverInstance -Database $database -TrustServerCertificate -ErrorAction Stop -Query "KILL $($r.spid)"
+                            $kills++
+                        }
+                    }
+                    catch { }
+                    Start-Sleep -Milliseconds 400
+                }
+                $kills
+            } -ArgumentList $server.ServerInstance, $db.Database
+            try {
+                $res = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Shrink `
+                    -AuthType $server.Auth -WaitAtLowPriority:$false -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                    -MinReclaimMBOverride 1 -StepMBOverride 10 -Sessions 3 -StatusIntervalSeconds 2 `
+                    -MaxRuntimeSecondsOverride 20 -PassThru -LogPath $rlog 6>$null
+            }
+            finally {
+                Close-ShrinkTestBlocker -Connection $blocker
+            }
+            $killCount = @(Receive-Job $killJob -Wait -AutoRemoveJob)[-1]
+            $rlogText = Get-Content -Raw -LiteralPath $rlog
+        }
+        AfterAll {
+            Remove-ShrinkTestDatabase -TestDb $db
+            if ($rlog -and (Test-Path $rlog)) { Remove-Item -LiteralPath $rlog -ErrorAction SilentlyContinue }
+        }
+
+        It 'reconnects a worker whose session was killed' {
+            $killCount | Should -BeGreaterThan 0
+            $rlogText | Should -Match 'reconnected on attempt'
+        }
+
+        It 'still accounts for every eligible file' {
+            $sum = ($res.Counts.PSObject.Properties | Measure-Object -Property Value -Sum).Sum
+            $sum | Should -Be $res.Files.Count
+        }
+    }
+
+    Context 'Concurrency (files > sessions)' -Skip:(-not $isBoxEngine) {
+        BeforeAll {
+            $db = New-ShrinkTestDatabase -Context $server -FileCount 6
+            Wait-ShrinkFreeSpaceSettled -TestDb $db -MinFreeMB 8 | Out-Null
+            $res = Invoke-ShrinkDriver -ServerName $server.ServerInstance -DatabaseName $db.Database -Mode Shrink `
+                -AuthType $server.Auth -WaitAtLowPriority:$false -BackoffBaseSeconds 0 -BackoffCapSeconds 0 `
+                -MinReclaimMBOverride 1 -StepMBOverride 20 -Sessions 2 -StatusIntervalSeconds 5 -PassThru -LogPath $log 6>$null
+        }
+        AfterAll { Remove-ShrinkTestDatabase -TestDb $db }
+
+        It 'exercises more files than sessions' {
+            # Sessions was capped at 2 while more eligible files exist, so a freed worker must pick up the rest.
+            $res.Files.Count | Should -BeGreaterThan 2
+        }
+
+        It 'accounts for every eligible file exactly once (counts tally to files; none dropped)' {
+            $sum = ($res.Counts.PSObject.Properties | Measure-Object -Property Value -Sum).Sum
+            $sum | Should -Be $res.Files.Count
+        }
+
+        It 'shrinks at least one file under limited concurrency' {
+            ($res.Counts.Shrunk + $res.Counts.PartlyShrunk) | Should -BeGreaterThan 0
+        }
+    }
+}
diff --git a/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1 b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1
new file mode 100644
index 0000000000..143e99dc0b
--- /dev/null
+++ b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1
@@ -0,0 +1,507 @@
+#requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+<#
+  Unit tests for ShrinkDriver.
+  Run:  Invoke-Pester -Path .\tests\ShrinkDriver.Unit.Tests.ps1
+#>
+
+BeforeAll {
+    # Dot-source the file to expose functions for testing.
+    . (Join-Path $PSScriptRoot '..\src\ShrinkDriver.ps1')
+}
+
+Describe 'Test-ShrinkParameterSet' {
+    It 'rejects TruncateOnly + NoTruncate together' {
+        $e = Test-ShrinkParameterSet @{ AuthType='EntraID'; Sessions=5; AbortAfterWait='SELF'; TruncateOnly=$true; NoTruncate=$true }
+        $e | Should -Not -BeNullOrEmpty
+        ($e -join ';') | Should -Match 'mutually exclusive'
+    }
+    It 'rejects TruncateOnly + FileTargetSizeGiB' {
+        $e = Test-ShrinkParameterSet @{ AuthType='EntraID'; Sessions=5; AbortAfterWait='SELF'; TruncateOnly=$true; FileTargetSizeGiB=100 }
+        ($e -join ';') | Should -Match 'FileTargetSizeGiB'
+    }
+    It 'requires a login for SQL auth (the password is prompted, not required)' {
+        $e = Test-ShrinkParameterSet @{ AuthType='SQL'; Sessions=5; AbortAfterWait='SELF' }
+        ($e -join ';') | Should -Match 'SqlLogin'
+        ($e -join ';') | Should -Not -Match 'SqlPassword'
+    }
+    It 'rejects a plain-text SqlPassword for SQL auth' {
+        $e = Test-ShrinkParameterSet @{ AuthType='SQL'; SqlLogin='u'; SqlPassword='p'; AbortAfterWait='SELF' }
+        ($e -join ';') | Should -Match 'SecureString'
+    }
+    It 'accepts a SecureString SqlPassword for SQL auth' {
+        $sec = ConvertTo-SecureString 'p' -AsPlainText -Force
+        $e = Test-ShrinkParameterSet @{ AuthType='SQL'; SqlLogin='u'; SqlPassword=$sec; AbortAfterWait='SELF' }
+        ($e -join ';') | Should -Not -Match 'SqlPassword'
+    }
+    It 'rejects an invalid AbortAfterWait' {
+        $e = Test-ShrinkParameterSet @{ AuthType='EntraID'; Sessions=5; AbortAfterWait='NONE' }
+        ($e -join ';') | Should -Match 'AbortAfterWait'
+    }
+    It 'accepts a valid EntraID parameter set' {
+        $e = Test-ShrinkParameterSet @{ AuthType='EntraID'; Sessions=5; AbortAfterWait='SELF'; TruncateOnly=$false; NoTruncate=$false }
+        $e | Should -BeNullOrEmpty
+    }
+}
+
+Describe 'Resolve-ShrinkLogPath' {
+    It 'returns the full path for a writable file in an existing directory' {
+        $p = Join-Path $TestDrive 'shrink.log'
+        Resolve-ShrinkLogPath -Path $p | Should -Be ([System.IO.Path]::GetFullPath($p))
+    }
+    It 'creates the file if it does not yet exist' {
+        $p = Join-Path $TestDrive 'created.log'
+        Resolve-ShrinkLogPath -Path $p | Out-Null
+        Test-Path -LiteralPath $p | Should -BeTrue
+    }
+    It 'resolves a relative path against the current location' {
+        Push-Location $TestDrive
+        try {
+            $expected = Join-Path (Get-Location).ProviderPath 'rel.log'
+            Resolve-ShrinkLogPath -Path 'rel.log' | Should -Be $expected
+        } finally { Pop-Location }
+    }
+    It 'throws when the directory does not exist' {
+        $p = Join-Path $TestDrive 'missing-dir\deep\x.log'
+        { Resolve-ShrinkLogPath -Path $p } | Should -Throw '*does not exist*'
+    }
+    It 'throws when the path is a directory' {
+        { Resolve-ShrinkLogPath -Path $TestDrive } | Should -Throw '*is a directory*'
+    }
+}
+
+Describe 'Numeric parameter validation' {
+    It '<Param> declares ValidateRange <Min>..<Max>' -TestCases @(
+        @{ Param = 'Sessions';              Min = 1; Max = [int]::MaxValue }
+        @{ Param = 'RetryCount';            Min = 0; Max = 50 }
+        @{ Param = 'FileTargetSizeGiB';     Min = 0; Max = [int]::MaxValue }
+        @{ Param = 'MaxRuntimeMinutes';     Min = 1; Max = [int]::MaxValue }
+        @{ Param = 'StepGiB';               Min = 1; Max = [int]::MaxValue }
+        @{ Param = 'MinReclaimGiB';         Min = 0; Max = [int]::MaxValue }
+        @{ Param = 'StatusIntervalSeconds'; Min = 1; Max = [int]::MaxValue }
+        @{ Param = 'StuckWindowSeconds';    Min = 1; Max = [int]::MaxValue }
+    ) {
+        $range = (Get-Command Invoke-ShrinkDriver).Parameters[$Param].Attributes |
+            Where-Object { $_ -is [ValidateRange] } | Select-Object -First 1
+        $range | Should -Not -BeNullOrEmpty
+        $range.MinRange | Should -Be $Min
+        $range.MaxRange | Should -Be $Max
+    }
+
+    It 'rejects <Param>=<Value> as out of range' -TestCases @(
+        @{ Param = 'Sessions';              Value = 0 }
+        @{ Param = 'RetryCount';            Value = -1 }
+        @{ Param = 'RetryCount';            Value = 51 }
+        @{ Param = 'FileTargetSizeGiB';     Value = -1 }
+        @{ Param = 'MaxRuntimeMinutes';     Value = 0 }
+        @{ Param = 'StepGiB';               Value = 0 }
+        @{ Param = 'MinReclaimGiB';         Value = -1 }
+        @{ Param = 'StatusIntervalSeconds'; Value = 0 }
+        @{ Param = 'StuckWindowSeconds';    Value = 0 }
+    ) {
+        $splat = @{ ServerName = 's'; DatabaseName = 'd'; $Param = $Value }
+        { Invoke-ShrinkDriver @splat } |
+            Should -Throw -ErrorId 'ParameterArgumentValidationError,Invoke-ShrinkDriver'
+    }
+}
+
+Describe 'Mode parameter' {
+    It 'allows only Report and Shrink' {
+        $vs = (Get-Command Invoke-ShrinkDriver).Parameters['Mode'].Attributes |
+            Where-Object { $_ -is [ValidateSet] } | Select-Object -First 1
+        $vs.ValidValues | Should -Contain 'Report'
+        $vs.ValidValues | Should -Contain 'Shrink'
+        $vs.ValidValues.Count | Should -Be 2
+    }
+    It 'rejects an invalid mode' {
+        { Invoke-ShrinkDriver -ServerName s -DatabaseName d -Mode Nope } |
+            Should -Throw -ErrorId 'ParameterArgumentValidationError,Invoke-ShrinkDriver'
+    }
+}
+
+Describe 'Get-ShrinkBackoffSeconds' {
+    It 'never exceeds min(cap, base*2^attempt) and is >= 0' {
+        $rng = [System.Random]::new(42)
+        foreach ($a in 0..10) {
+            $cap = [Math]::Min(60, 5 * [Math]::Pow(2, $a))
+            $v = Get-ShrinkBackoffSeconds -Attempt $a -BaseSec 5 -CapSec 60 -Random $rng
+            $v | Should -BeGreaterOrEqual 0
+            $v | Should -BeLessOrEqual $cap
+        }
+    }
+    It 'is deterministic with a seeded RNG' {
+        $a = Get-ShrinkBackoffSeconds -Attempt 3 -Random ([System.Random]::new(7))
+        $b = Get-ShrinkBackoffSeconds -Attempt 3 -Random ([System.Random]::new(7))
+        $a | Should -Be $b
+    }
+}
+
+Describe 'Format-ShrinkKeyValueTable' {
+    It 'pads labels to the widest key and keeps the colon aligned' {
+        $lines = Format-ShrinkKeyValueTable -Rows ([ordered]@{ 'A' = 1; 'Longer' = 2 })
+        $lines.Count | Should -Be 2
+        $lines[1] | Should -Be '  Longer : 2'
+        $lines[0] | Should -Match '^\s{2}A\s+: 1$'
+        $lines[0].IndexOf(':') | Should -Be ($lines[1].IndexOf(':'))
+    }
+}
+
+Describe 'Format-ShrinkTable' {
+    It 'returns nothing for an empty set' {
+        @(Format-ShrinkTable -Rows @()) | Should -BeNullOrEmpty
+    }
+    It 'renders a header, separator, and one line per row' {
+        $rows = @(
+            [ordered]@{ A = '1';  Name = 'x';  B = '10' }
+            [ordered]@{ A = '22'; Name = 'yy'; B = '3' }
+        )
+        $lines = @(Format-ShrinkTable -Rows $rows -RightAlign @('A', 'B'))
+        $lines.Count | Should -Be 4
+        $lines[0] | Should -Match 'A\s+Name\s+B'
+        $lines[1] | Should -Match '^-+\s+-+\s+-+$'
+    }
+    It 'right-aligns listed columns and left-aligns the rest' {
+        $rows = @(
+            [ordered]@{ Name = 'a';  Val = '1' }
+            [ordered]@{ Name = 'bb'; Val = '100' }
+        )
+        $lines = @(Format-ShrinkTable -Rows $rows -RightAlign @('Val'))
+        # Name left-aligned (short value flush left), Val right-aligned (short value padded left).
+        $lines[2] | Should -Match '^a\s+\S*1$'
+        $lines[3] | Should -Match '^bb\s+100$'
+    }
+}
+
+Describe 'Test-ShrinkWorthwhile' {
+    It 'is worthwhile when reclaimable meets the minimum' {
+        Test-ShrinkWorthwhile -AllocatedMB 1000 -UsedMB 100 -MinReclaimMB 100 | Should -BeTrue
+    }
+    It 'is not worthwhile when reclaimable is below the minimum' {
+        Test-ShrinkWorthwhile -AllocatedMB 1000 -UsedMB 950 -MinReclaimMB 100 | Should -BeFalse
+    }
+    It 'treats exactly the minimum as worthwhile' {
+        Test-ShrinkWorthwhile -AllocatedMB 1000 -UsedMB 900 -MinReclaimMB 100 | Should -BeTrue
+    }
+    It 'uses the larger of used pages and the target floor' {
+        Test-ShrinkWorthwhile -AllocatedMB 1000 -UsedMB 100 -FloorMB 950 -MinReclaimMB 100 | Should -BeFalse
+    }
+    It 'is not worthwhile for a zero-size file' {
+        Test-ShrinkWorthwhile -AllocatedMB 0 -UsedMB 0 -MinReclaimMB 100 | Should -BeFalse
+    }
+    It 'ignores a tiny gain on a large file' {
+        Test-ShrinkWorthwhile -AllocatedMB 100000 -UsedMB 99950 -MinReclaimMB 100 | Should -BeFalse
+    }
+}
+
+Describe 'Get-ShrinkReclaimableMB' {
+    It 'is allocated minus used with no floor' {
+        Get-ShrinkReclaimableMB -AllocatedMB 1000 -UsedMB 200 | Should -Be 800
+    }
+    It 'uses the target floor when it is larger than used' {
+        Get-ShrinkReclaimableMB -AllocatedMB 1000 -UsedMB 200 -FloorMB 600 | Should -Be 400
+    }
+    It 'ignores the target floor when used is larger' {
+        Get-ShrinkReclaimableMB -AllocatedMB 1000 -UsedMB 700 -FloorMB 600 | Should -Be 300
+    }
+    It 'never returns a negative value' {
+        Get-ShrinkReclaimableMB -AllocatedMB 100 -UsedMB 500 | Should -Be 0
+    }
+}
+
+Describe 'Get-ShrinkSumMB' {
+    It 'sums the property across items' {
+        $items = @([pscustomobject]@{ V = 10 }, [pscustomobject]@{ V = 32 })
+        Get-ShrinkSumMB -Items $items -Property V | Should -Be 42
+    }
+    It 'returns 0 for an empty set' {
+        Get-ShrinkSumMB -Items @() -Property V | Should -Be 0
+    }
+}
+
+Describe 'Get-ShrinkSizeUnit' {
+    It 'picks <unit> for <mb> MiB' -TestCases @(
+        @{ Mb = 0.5;      Unit = 'KiB' }
+        @{ Mb = 500;      Unit = 'MiB' }
+        @{ Mb = 2048;     Unit = 'GiB' }
+        @{ Mb = 2097152;  Unit = 'TiB' }
+    ) {
+        (Get-ShrinkSizeUnit -MaxMegabytes $Mb).Name | Should -Be $Unit
+    }
+}
+
+Describe 'Format-ShrinkFileReport' {
+    It 'includes a header row' {
+        $files = 1..3 | ForEach-Object { [pscustomobject]@{ FileId = $_; Name = "f$_"; UsedMB = 10; AllocatedMB = ($_ * 1000); ReclaimableMB = ($_ * 1000 - 10); IsEligible = $true } }
+        (@(Format-ShrinkFileReport -Files $files) -join "`n") | Should -Match 'File\s+Name\s+Used \(\w+\)\s+Allocated \(\w+\)\s+Reclaimable \(\w+\)\s+Eligible'
+    }
+    It 'uses one unit for the whole table, noted in the header' {
+        $files = @(
+            [pscustomobject]@{ FileId = 1; Name = 'big';  UsedMB = 1; AllocatedMB = (50 * 1024); ReclaimableMB = (50 * 1024 - 1); IsEligible = $true }
+            [pscustomobject]@{ FileId = 2; Name = 'tiny'; UsedMB = 1; AllocatedMB = 8;           ReclaimableMB = 7;             IsEligible = $false }
+        )
+        $lines = @(Format-ShrinkFileReport -Files $files)
+        $lines[0] | Should -Match 'Used \(GiB\)'
+        $lines[0] | Should -Match 'Allocated \(GiB\)'
+        $lines[0] | Should -Match 'Reclaimable \(GiB\)'
+        # The tiny file is shown in the table's GiB unit (rounds to 0.0), not its own MiB unit.
+        $tinyRow = $lines | Where-Object { $_ -match '^\s*2\s+tiny\s' }
+        $tinyRow | Should -Match '0\.0'
+        ($lines | Where-Object { $_ -match 'MiB|KiB|TiB' }) | Should -BeNullOrEmpty
+    }
+    It 'lists the most reclaimable file first' {
+        $files = 1..3 | ForEach-Object { [pscustomobject]@{ FileId = $_; Name = "f$_"; UsedMB = 10; AllocatedMB = ($_ * 1000); ReclaimableMB = ($_ * 1000 - 10); IsEligible = $true } }
+        $lines = @(Format-ShrinkFileReport -Files $files)
+        $lines[2] | Should -Match '^\s*3\s+f3'
+    }
+    It 'limits to TopN and notes the omitted files' {
+        $many = 1..150 | ForEach-Object { [pscustomobject]@{ FileId = $_; Name = "f$_"; UsedMB = 1; AllocatedMB = ($_ * 10); ReclaimableMB = ($_ * 10 - 1); IsEligible = $true } }
+        $lines = @(Format-ShrinkFileReport -Files $many -TopN 100)
+        ($lines | Where-Object { $_ -match '50 other file\(s\) omitted' }) | Should -Not -BeNullOrEmpty
+        $lines.Count | Should -Be 103
+    }
+    It 'renders the eligibility column as Yes or No' {
+        $files = @(
+            [pscustomobject]@{ FileId = 1; Name = 'a'; UsedMB = 10; AllocatedMB = 5000; ReclaimableMB = 4990; IsEligible = $true }
+            [pscustomobject]@{ FileId = 2; Name = 'b'; UsedMB = 10; AllocatedMB = 20;   ReclaimableMB = 10;   IsEligible = $false }
+        )
+        $lines = @(Format-ShrinkFileReport -Files $files)
+        ($lines | Where-Object { $_ -match '^\s*1\s+a\s' }) | Should -Match 'Yes'
+        ($lines | Where-Object { $_ -match '^\s*2\s+b\s' }) | Should -Match 'No'
+    }
+    It 'handles an empty set' {
+        @(Format-ShrinkFileReport -Files @()) | Should -Be '(no data files found)'
+    }
+}
+
+Describe 'Get-ShrinkNextTargetMB' {
+    It 'steps down by 20 GiB by default' {
+        Get-ShrinkNextTargetMB -AllocatedMB 100000 | Should -Be (100000 - 20480)
+    }
+    It 'never goes below the floor' {
+        Get-ShrinkNextTargetMB -AllocatedMB 12000 -FloorMB 10000 | Should -Be 10000
+    }
+    It 'clamps to the floor when a full step would overshoot it' {
+        Get-ShrinkNextTargetMB -AllocatedMB 10500 -FloorMB 10000 | Should -Be 10000
+    }
+    It 'never returns 0, since DBCC reads target 0 as the file creation size' {
+        Get-ShrinkNextTargetMB -AllocatedMB 10240 | Should -Be 1
+    }
+    It 'clamps an allocation within one step of 0 to 1 rather than 0' {
+        Get-ShrinkNextTargetMB -AllocatedMB 3000 | Should -Be 1
+    }
+}
+
+Describe 'Select-ShrinkNextFile' {
+    BeforeAll {
+        $script:files = @(
+            [pscustomobject]@{ FileId=1; AllocatedMB=1000; UsedMB=900; FloorMB=$null }  # reclaim 100
+            [pscustomobject]@{ FileId=2; AllocatedMB=1000; UsedMB=200; FloorMB=$null }  # reclaim 800
+            [pscustomobject]@{ FileId=3; AllocatedMB=1000; UsedMB=1000; FloorMB=$null } # reclaim 0
+        )
+    }
+    It 'picks the most reclaimable file' {
+        (Select-ShrinkNextFile -Files $script:files).FileId | Should -Be 2
+    }
+    It 'skips owned and excluded files' {
+        (Select-ShrinkNextFile -Files $script:files -OwnedFileIds @(2) -ExcludedFileIds @()).FileId | Should -Be 1
+    }
+    It 'skips files that already reached a terminal state' {
+        (Select-ShrinkNextFile -Files $script:files -ExcludedFileIds @(2)).FileId | Should -Be 1
+    }
+    It 'returns null when nothing is reclaimable' {
+        Select-ShrinkNextFile -Files @($script:files[2]) | Should -BeNullOrEmpty
+    }
+    It 'ranks by reclaimable space above the floor, not raw unused space' {
+        # File 1 has more raw unused space (900) but a floor that leaves only 100 reclaimable; file 2
+        # has less unused space (500) but no floor, so 500 is reclaimable and it should be picked first.
+        $files = @(
+            [pscustomobject]@{ FileId = 1; AllocatedMB = 1000; UsedMB = 100; FloorMB = 900 } # reclaim 100
+            [pscustomobject]@{ FileId = 2; AllocatedMB = 1000; UsedMB = 500; FloorMB = $null } # reclaim 500
+        )
+        (Select-ShrinkNextFile -Files $files).FileId | Should -Be 2
+    }
+}
+
+Describe 'Get-ShrinkBucketCounts' {
+    It 'tallies each bucket' {
+        $c = Get-ShrinkBucketCounts -Buckets @('Shrunk','Shrunk','AlreadyMinimal','AlreadyAtTarget','GaveUp','Shrunk','PartlyShrunk','Grew','Repacked','Repacked','Interrupted','NotProcessed','NotProcessed')
+        $c.Shrunk | Should -Be 3
+        $c.Repacked | Should -Be 2
+        $c.PartlyShrunk | Should -Be 1
+        $c.AlreadyMinimal | Should -Be 1
+        $c.AlreadyAtTarget | Should -Be 1
+        $c.Grew | Should -Be 1
+        $c.GaveUp | Should -Be 1
+        $c.Interrupted | Should -Be 1
+        $c.NotProcessed | Should -Be 2
+    }
+    It 'returns zeros for an empty set' {
+        $c = Get-ShrinkBucketCounts -Buckets @()
+        $c.Shrunk | Should -Be 0
+        $c.Repacked | Should -Be 0
+        $c.PartlyShrunk | Should -Be 0
+        $c.AlreadyMinimal | Should -Be 0
+        $c.AlreadyAtTarget | Should -Be 0
+        $c.Grew | Should -Be 0
+        $c.GaveUp | Should -Be 0
+        $c.Interrupted | Should -Be 0
+        $c.NotProcessed | Should -Be 0
+    }
+}
+
+Describe 'Get-ShrinkGaveUpBucket' {
+    It 'classifies a net reduction as PartlyShrunk' {
+        Get-ShrinkGaveUpBucket -StartAllocMB 1000 -FinalAllocMB 600 | Should -Be 'PartlyShrunk'
+    }
+    It 'classifies a net growth as Grew' {
+        Get-ShrinkGaveUpBucket -StartAllocMB 1000 -FinalAllocMB 1200 | Should -Be 'Grew'
+    }
+    It 'classifies no change as GaveUp' {
+        Get-ShrinkGaveUpBucket -StartAllocMB 1000 -FinalAllocMB 1000 | Should -Be 'GaveUp'
+    }
+}
+
+Describe 'Get-ShrinkStopOutcome' {
+    It 'reports Interrupted on a forced quit regardless of sizes' {
+        $o = Get-ShrinkStopOutcome -StartAllocMB 1000 -FinalAllocMB 600 -Cause 'Ctrl+C' -Force
+        $o.Bucket | Should -Be 'Interrupted'
+        $o.Reason | Should -Match 'twice'
+    }
+    It 'reports PartlyShrunk when the file ended smaller' {
+        (Get-ShrinkStopOutcome -StartAllocMB 1000 -FinalAllocMB 600 -Cause 'Timeout').Bucket | Should -Be 'PartlyShrunk'
+    }
+    It 'reports Grew when the file ended larger' {
+        (Get-ShrinkStopOutcome -StartAllocMB 1000 -FinalAllocMB 1200 -Cause 'Ctrl+C').Bucket | Should -Be 'Grew'
+    }
+    It 'reports Interrupted (no progress) when the size is unchanged' {
+        (Get-ShrinkStopOutcome -StartAllocMB 1000 -FinalAllocMB 1000 -Cause 'Timeout').Bucket | Should -Be 'Interrupted'
+    }
+    It 'reports Interrupted when the file was never measured (null start)' {
+        (Get-ShrinkStopOutcome -StartAllocMB $null -FinalAllocMB $null -Cause 'Ctrl+C').Bucket | Should -Be 'Interrupted'
+    }
+    It 'reports Interrupted when the final size could not be read (null final)' {
+        (Get-ShrinkStopOutcome -StartAllocMB 1000 -FinalAllocMB $null -Cause 'Timeout').Bucket | Should -Be 'Interrupted'
+    }
+    It 'uses a run-time-limit reason for the Timeout cause' {
+        (Get-ShrinkStopOutcome -StartAllocMB 1000 -FinalAllocMB 600 -Cause 'Timeout').Reason | Should -Match 'run time limit'
+    }
+    It 'uses a Ctrl+C reason for the Ctrl+C cause' {
+        (Get-ShrinkStopOutcome -StartAllocMB 1000 -FinalAllocMB 600 -Cause 'Ctrl+C').Reason | Should -Match 'Ctrl\+C'
+    }
+}
+
+Describe 'Get-ShrinkTotalsRows' {
+    It 'builds the run-time, size, and bucket rows in order' {
+        $counts = Get-ShrinkBucketCounts -Buckets @('Shrunk', 'Grew')
+        $rows = Get-ShrinkTotalsRows -RunTime '1m 2s' -Used '10.0 GiB' -Allocated '20.0 GiB' -Counts $counts
+        @($rows.Keys) | Should -Be @('Run time', 'Used', 'Allocated', 'Shrunk', 'Repacked', 'Partly shrunk', 'Already at minimum', 'Already at target', 'Grew', 'Gave up', 'Interrupted', 'Not processed')
+        $rows['Run time']  | Should -Be '1m 2s'
+        $rows['Used']      | Should -Be '10.0 GiB'
+        $rows['Allocated'] | Should -Be '20.0 GiB'
+        $rows['Shrunk']    | Should -Be 1
+        $rows['Grew']      | Should -Be 1
+        $rows['Gave up']   | Should -Be 0
+    }
+}
+
+Describe 'Get-ShrinkDeltaWithReset' {
+    It 'returns a positive delta when increasing' {
+        $r = Get-ShrinkDeltaWithReset -Previous 100 -Current 150
+        $r.IsReset | Should -BeFalse
+        $r.Delta | Should -Be 50
+    }
+    It 'flags a reset when the counter decreases' {
+        $r = Get-ShrinkDeltaWithReset -Previous 100 -Current 10
+        $r.IsReset | Should -BeTrue
+        $r.Delta | Should -BeNullOrEmpty
+    }
+}
+
+Describe 'Update-ShrinkStuckState' {
+    It 'fires when the same non-zero blocker persists for the window, even while CPU advances' {
+        $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
+        $t0 = Get-Date
+        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300).IsStuck | Should -BeFalse
+        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 999 -Reads 999 -Now $t0.AddSeconds(310) -WindowSec 300).IsStuck | Should -BeTrue
+    }
+    It 'fires when neither CPU nor reads advance for the window, with no blocker' {
+        $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
+        $t0 = Get-Date
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300).IsStuck | Should -BeFalse
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -Now $t0.AddSeconds(310) -WindowSec 300).IsStuck | Should -BeTrue
+    }
+    It 'does not fire while CPU or reads keep advancing and there is no blocker' {
+        $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
+        $t0 = Get-Date
+        Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 20 -Reads 30 -Now $t0.AddSeconds(400) -WindowSec 300).IsStuck | Should -BeFalse
+    }
+    It 'treats a per-request counter reset as progress' {
+        $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
+        $t0 = Get-Date
+        Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 500 -Reads 500 -Now $t0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 5 -Reads 5 -Now $t0.AddSeconds(310) -WindowSec 300).IsStuck | Should -BeFalse
+    }
+    It 'restarts the blocker streak when the blocker changes' {
+        $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
+        $t0 = Get-Date
+        Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 77 -Cpu 20 -Reads 20 -Now $t0.AddSeconds(400) -WindowSec 300).IsStuck | Should -BeFalse
+    }
+    It 'does not fire within the window' {
+        $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
+        $t0 = Get-Date
+        Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0.AddSeconds(120) -WindowSec 300).IsStuck | Should -BeFalse
+    }
+}
+
+Describe 'New-ShrinkRetryProvider' {
+    It 'returns a provider when configurable retry is available, otherwise null, without throwing' {
+        $provider = New-ShrinkRetryProvider
+        if ('Microsoft.Data.SqlClient.SqlConfigurableRetryFactory' -as [type]) {
+            $provider | Should -Not -BeNullOrEmpty
+        } else {
+            $provider | Should -BeNullOrEmpty
+        }
+    }
+}
+
+Describe 'New-ShrinkCommandText' {
+    It 'builds a plain target shrink with NO_INFOMSGS' {
+        $c = New-ShrinkCommandText -FileId 3 -TargetMB 52000
+        $c | Should -Be 'DBCC SHRINKFILE (3, 52000) WITH NO_INFOMSGS'
+    }
+    It 'builds TRUNCATEONLY without a target' {
+        New-ShrinkCommandText -FileId 1 -TruncateOnly | Should -Be 'DBCC SHRINKFILE (1, TRUNCATEONLY) WITH NO_INFOMSGS'
+    }
+    It 'appends NOTRUNCATE to a target shrink' {
+        New-ShrinkCommandText -FileId 2 -TargetMB 1000 -NoTruncate |
+            Should -Be 'DBCC SHRINKFILE (2, 1000, NOTRUNCATE) WITH NO_INFOMSGS'
+    }
+    It 'adds WLP with SELF' {
+        $c = New-ShrinkCommandText -FileId 5 -TargetMB 1 -WaitAtLowPriority -AbortAfterWait SELF
+        $c | Should -Match 'WAIT_AT_LOW_PRIORITY \(ABORT_AFTER_WAIT = SELF\)'
+    }
+    It 'adds WLP with BLOCKERS' {
+        New-ShrinkCommandText -FileId 5 -TargetMB 1 -WaitAtLowPriority -AbortAfterWait BLOCKERS |
+            Should -Match 'ABORT_AFTER_WAIT = BLOCKERS'
+    }
+    It 'throws on TruncateOnly + NoTruncate' {
+        { New-ShrinkCommandText -FileId 1 -TruncateOnly -NoTruncate } | Should -Throw
+    }
+}
+
+Describe 'Format-ShrinkSize' {
+    It 'formats <Mb> MiB as <Text>' -TestCases @(
+        @{ Mb = 0;       Text = '0 KiB' }
+        @{ Mb = 0.5;     Text = '512 KiB' }
+        @{ Mb = 1;       Text = '1.0 MiB' }
+        @{ Mb = 8;       Text = '8.0 MiB' }
+        @{ Mb = 1024;    Text = '1.0 GiB' }
+        @{ Mb = 1536;    Text = '1.5 GiB' }
+        @{ Mb = 1048576; Text = '1.0 TiB' }
+        @{ Mb = 1572864; Text = '1.5 TiB' }
+    ) {
+        Format-ShrinkSize -Megabytes $Mb | Should -Be $Text
+    }
+}
diff --git a/samples/features/shrink/shrink-driver/tests/fixtures/ShrinkTestDb.psm1 b/samples/features/shrink/shrink-driver/tests/fixtures/ShrinkTestDb.psm1
new file mode 100644
index 0000000000..f6c6442e19
--- /dev/null
+++ b/samples/features/shrink/shrink-driver/tests/fixtures/ShrinkTestDb.psm1
@@ -0,0 +1,333 @@
+<#
+.SYNOPSIS
+  Test fixtures for the ShrinkDriver integration tests: provision, populate, and tear down a small
+  throwaway database with several data files and interspersed free space. Works against box SQL Server
+  / LocalDB and Azure SQL Database (engine-aware provisioning).
+
+  Not a Pester test file (no *.Tests.ps1 suffix), so Pester does not execute it as tests.
+
+  Portability notes:
+  - All data files live in PRIMARY (Azure SQL Database has no user filegroups).
+  - Rows are generated with a portable TOP/ROW_NUMBER query over sys.all_objects.
+  - Connections use Microsoft.Data.SqlClient with the same auth options as the driver itself
+    (Windows / EntraID with Active Directory Default then Interactive fallback / SQL).
+#>
+
+# Ensure Microsoft.Data.SqlClient is loaded (the SqlServer module ships it). Needed at import time so
+# Get-ShrinkTestServer works during Pester discovery, before the driver script is dot-sourced.
+if (-not ('Microsoft.Data.SqlClient.SqlConnection' -as [type])) {
+    Import-Module SqlServer -ErrorAction Stop
+}
+
+# ----- connection layer (Microsoft.Data.SqlClient; mirrors the driver's auth) -----
+
+function New-ShrinkTestConnection {
+    [CmdletBinding()][OutputType([Microsoft.Data.SqlClient.SqlConnection])]
+    param(
+        [Parameter(Mandatory)][string]$ServerInstance,
+        [string]$Database = 'master',
+        [ValidateSet('Windows', 'EntraID', 'SQL')][string]$Auth = 'Windows',
+        [string]$SqlLogin,
+        [securestring]$SqlPassword,
+        [bool]$TrustServerCertificate = $false
+    )
+    $csb = [Microsoft.Data.SqlClient.SqlConnectionStringBuilder]::new()
+    $csb['Data Source'] = $ServerInstance
+    $csb['Initial Catalog'] = $Database
+    $csb['Encrypt'] = $true
+    $csb['TrustServerCertificate'] = $TrustServerCertificate
+    $csb['Connect Timeout'] = 60
+    $csb['Pooling'] = $false
+    $conn = [Microsoft.Data.SqlClient.SqlConnection]::new()
+    switch ($Auth) {
+        'Windows' {
+            $csb['Integrated Security'] = $true
+            $conn.ConnectionString = $csb.ConnectionString
+            $conn.Open()
+        }
+        'SQL' {
+            $conn.ConnectionString = $csb.ConnectionString
+            # Resolve the SQL password securely: use the SecureString passed in, else one already
+            # entered this session, else prompt for it. It is never stored or read as clear text.
+            $pw = if ($SqlPassword) { $SqlPassword }
+                  elseif ($global:ShrinkTestSqlPassword) { $global:ShrinkTestSqlPassword }
+                  else { $global:ShrinkTestSqlPassword = Read-Host -AsSecureString "SQL password for login '$SqlLogin'"; $global:ShrinkTestSqlPassword }
+            if (-not $pw.IsReadOnly()) { $pw.MakeReadOnly() }
+            $conn.Credential = [Microsoft.Data.SqlClient.SqlCredential]::new($SqlLogin, $pw)
+            $conn.Open()
+        }
+        'EntraID' {
+            # Try the ambient credential first, then fall back to an interactive sign-in (browser),
+            # exactly as the driver's New-ShrinkConnection does.
+            foreach ($mode in @('Active Directory Default', 'Active Directory Interactive')) {
+                $csb['Authentication'] = $mode
+                $conn.ConnectionString = $csb.ConnectionString
+                try { $conn.Open(); break }
+                catch { if ($mode -eq 'Active Directory Interactive') { throw } }
+            }
+        }
+    }
+    $conn
+}
+
+function Invoke-ShrinkTestSql {
+    <#
+    .SYNOPSIS
+      Run a T-SQL batch on a fresh connection and return any result-set rows as PSCustomObjects.
+      Drains all result sets so every statement in a multi-statement batch executes.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Context,   # ServerInstance / Auth / SqlLogin / SqlPassword
+        [Parameter(Mandatory)][string]$Query,
+        [string]$Database = 'master',
+        [int]$CommandTimeout = 300
+    )
+    $conn = New-ShrinkTestConnection -ServerInstance $Context.ServerInstance -Database $Database `
+        -Auth $Context.Auth -SqlLogin $Context.SqlLogin -SqlPassword $Context.SqlPassword `
+        -TrustServerCertificate ([bool]$Context.TrustServerCertificate)
+    try {
+        $cmd = $conn.CreateCommand(); $cmd.CommandText = $Query; $cmd.CommandTimeout = $CommandTimeout
+        $rd = $cmd.ExecuteReader()
+        $rows = [System.Collections.Generic.List[object]]::new()
+        try {
+            do {
+                while ($rd.Read()) {
+                    $o = [ordered]@{}
+                    for ($i = 0; $i -lt $rd.FieldCount; $i++) {
+                        $name = $rd.GetName($i)
+                        if ([string]::IsNullOrEmpty($name)) { $name = "Column$i" }
+                        $o[$name] = if ($rd.IsDBNull($i)) { $null } else { $rd.GetValue($i) }
+                    }
+                    $rows.Add([pscustomobject]$o)
+                }
+            } while ($rd.NextResult())
+        }
+        finally { $rd.Dispose(); $cmd.Dispose() }
+        # Emit rows so a pipeline (e.g. Measure-Object) enumerates them individually. Consumers that
+        # index the first row with (...)[0] still work for single-row results.
+        $rows.ToArray()
+    }
+    finally { $conn.Dispose() }
+}
+
+# ----- discovery -----
+
+function Get-ShrinkTestServer {
+    <#
+    .SYNOPSIS
+      Resolve a SQL target for integration tests as a context object
+      { ServerInstance, Auth, SqlLogin, SqlPassword, TrustServerCertificate }, or $null if none is
+      reachable. Honors $env:SHRINKDRIVER_TEST_SERVER (+ _AUTH / _LOGIN / _TRUSTCERT); for SQL auth the
+      password is prompted for securely at connect time. Otherwise falls back to SQL Server LocalDB with
+      Windows auth.
+    #>
+    [CmdletBinding()][OutputType([pscustomobject])]
+    param()
+
+    if ($env:SHRINKDRIVER_TEST_SERVER) {
+        $auth = if ($env:SHRINKDRIVER_TEST_AUTH) { $env:SHRINKDRIVER_TEST_AUTH } else { 'EntraID' }
+        return [pscustomobject]@{
+            ServerInstance         = $env:SHRINKDRIVER_TEST_SERVER
+            Auth                   = $auth
+            SqlLogin               = $env:SHRINKDRIVER_TEST_LOGIN
+            SqlPassword            = $null   # SQL-auth password is prompted for securely at connect time, never stored as clear text
+            # Trust a self-signed certificate only when explicitly opted in, e.g. a local
+            # dev build.
+            TrustServerCertificate = [bool]($env:SHRINKDRIVER_TEST_TRUSTCERT -in @('1', 'true', 'yes'))
+        }
+    }
+
+    $localDbExe = Get-Command sqllocaldb -ErrorAction SilentlyContinue
+    if (-not $localDbExe) { return $null }
+    try {
+        & sqllocaldb start MSSQLLocalDB *> $null
+        $ctx = [pscustomobject]@{ ServerInstance = '(localdb)\MSSQLLocalDB'; Auth = 'Windows'; SqlLogin = $null; SqlPassword = $null; TrustServerCertificate = [bool]($env:SHRINKDRIVER_TEST_TRUSTCERT -in @('1', 'true', 'yes')) }
+        Invoke-ShrinkTestSql -Context $ctx -Query 'SELECT 1 AS ok;' -Database master | Out-Null
+        return $ctx
+    }
+    catch { return $null }
+}
+
+function Get-ShrinkTestEngineEdition {
+    [CmdletBinding()][OutputType([int])]
+    param([Parameter(Mandatory)][pscustomobject]$Context, [string]$Database = 'master')
+    [int](Invoke-ShrinkTestSql -Context $Context -Database $Database -Query "SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS ee;")[0].ee
+}
+
+# ----- provisioning -----
+
+function New-ShrinkTestDatabase {
+    <#
+    .SYNOPSIS
+      Create a throwaway test database with several data files in PRIMARY, fill it with page-packed
+      rows, then create interspersed free space by dropping every other table. Engine-aware:
+      - box SQL Server / LocalDB: CREATE DATABASE with explicit multiple PRIMARY files.
+      - Azure SQL Database (EngineEdition 5): CREATE DATABASE with a General Purpose service objective.
+        An Azure SQL Database has a single data file at the outset. So on Azure
+        the descriptor's FileCount is 1 and the multi-file / concurrency tests skip there.
+      Returns a descriptor carrying the connection context plus { Database, DataDir, Engine, FileCount }.
+    #>
+    [CmdletBinding()][OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$Context,
+        [string]$Database = ('ShrinkTest_{0}' -f [guid]::NewGuid().ToString('N').Substring(0, 8)),
+        [int]$FileCount = 4,
+        [int]$Tables = 16,
+        [int]$RowsPerTable = 2000,   # ~15.6 MB per table (char(8000) => 1 row/page)
+        [string]$DataDir,
+        [string]$AzureServiceObjective = 'GP_Gen5_2',
+        [int]$AzureMaxSizeGB = 32   # GP reserves storage up to maxsize; file count is independent of it (verified), so keep it small
+    )
+
+    $engine = Get-ShrinkTestEngineEdition -Context $Context
+    $isAzureDb = ($engine -eq 5)
+
+    if ($isAzureDb) {
+        # A General Purpose database always has a single ROWS data file at creation,
+        # so FileCount is 1 here and the multi-file tests skip on this platform.
+        Invoke-ShrinkTestSql -Context $Context -Database master -CommandTimeout 120 -Query @"
+CREATE DATABASE [$Database] (EDITION = 'GeneralPurpose', SERVICE_OBJECTIVE = '$AzureServiceObjective', MAXSIZE = $AzureMaxSizeGB GB);
+"@ | Out-Null
+    }
+    else {
+        if (-not $DataDir) { $DataDir = Join-Path ([System.IO.Path]::GetTempPath()) ('shrinktest_' + $Database) }
+        New-Item -ItemType Directory -Force -Path $DataDir | Out-Null
+        $addedFiles = (2..($FileCount + 1) | ForEach-Object { " (NAME='${Database}_$_', FILENAME='$DataDir\${Database}_$_.ndf', SIZE=8MB, FILEGROWTH=16MB)" }) -join ",`n"
+        Invoke-ShrinkTestSql -Context $Context -Database master -CommandTimeout 120 -Query @"
+IF DB_ID('$Database') IS NOT NULL BEGIN ALTER DATABASE [$Database] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE [$Database]; END;
+CREATE DATABASE [$Database] ON PRIMARY
+ (NAME='${Database}_1', FILENAME='$DataDir\$Database.mdf', SIZE=16MB, FILEGROWTH=16MB),
+$addedFiles
+ LOG ON (NAME='${Database}_log', FILENAME='$DataDir\${Database}_log.ldf', SIZE=64MB, FILEGROWTH=64MB);
+"@ | Out-Null
+    }
+
+    # Fill in one batch (portable row generator). Then drop every other table to leave interspersed
+    # free space (forces the page-movement shrink path, not just a tail truncate).
+    $fill = [System.Text.StringBuilder]::new()
+    [void]$fill.AppendLine('SET NOCOUNT ON;')
+    for ($t = 1; $t -le $Tables; $t++) {
+        [void]$fill.AppendLine("CREATE TABLE dbo.t$t (id int NOT NULL, filler char(8000) NOT NULL) ON [PRIMARY];")
+        [void]$fill.AppendLine("INSERT INTO dbo.t$t (id, filler) SELECT TOP ($RowsPerTable) ROW_NUMBER() OVER (ORDER BY (SELECT 1)), REPLICATE('x', 8000) FROM sys.all_objects a CROSS JOIN sys.all_objects b;")
+    }
+    Invoke-ShrinkTestSql -Context $Context -Database $Database -Query $fill.ToString() -CommandTimeout 600 | Out-Null
+
+    $drop = [System.Text.StringBuilder]::new()
+    for ($t = 1; $t -le $Tables; $t += 2) { [void]$drop.AppendLine("DROP TABLE dbo.t$t;") }
+    Invoke-ShrinkTestSql -Context $Context -Database $Database -Query $drop.ToString() | Out-Null
+
+    # Actual number of data (ROWS) files (the platform decides this on Azure General Purpose).
+    $dataFileCount = [int](Invoke-ShrinkTestSql -Context $Context -Database $Database -Query "SELECT COUNT(*) AS n FROM sys.database_files WHERE type_desc = 'ROWS';")[0].n
+
+    [pscustomobject]@{
+        ServerInstance = $Context.ServerInstance
+        Auth           = $Context.Auth
+        SqlLogin       = $Context.SqlLogin
+        SqlPassword    = $Context.SqlPassword
+        TrustServerCertificate = $Context.TrustServerCertificate
+        Database       = $Database
+        DataDir        = $DataDir
+        Engine         = $engine
+        FileCount      = $dataFileCount
+    }
+}
+
+function Wait-ShrinkFreeSpaceSettled {
+    <#
+    .SYNOPSIS
+      Wait until deferred deallocation is reflected in FILEPROPERTY 'SpaceUsed' (DROP TABLE space
+      release lags, even on a box engine). Polls until the minimum free MB across the data files has
+      reached $MinFreeMB and stopped growing (settled), or the timeout elapses. Returns the observed
+      minimum free MB.
+    #>
+    [CmdletBinding()][OutputType([int])]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$TestDb,
+        [int]$MinFreeMB = 8,
+        [int]$TimeoutSeconds = 120
+    )
+    $sql = "SELECT CAST(size/128.0 AS int) - CAST(FILEPROPERTY(name,'SpaceUsed')/128.0 AS int) AS free_mb FROM sys.database_files WHERE type_desc = 'ROWS';"
+    $sw = [System.Diagnostics.Stopwatch]::StartNew()
+    $minFree = 0; $prevMin = -1
+    do {
+        Invoke-ShrinkTestSql -Context $TestDb -Database $TestDb.Database -Query 'CHECKPOINT;' | Out-Null
+        Start-Sleep -Milliseconds 800
+        $rows = @(Invoke-ShrinkTestSql -Context $TestDb -Database $TestDb.Database -Query $sql)
+        $minFree = [int]($rows | Measure-Object -Property free_mb -Minimum).Minimum
+        # Settle once the reclaimable space has reached the floor and stopped growing between polls, so a
+        # later shrink sees the real free space rather than a still-deallocating snapshot.
+        $settled = ($minFree -ge $MinFreeMB) -and ($minFree -eq $prevMin)
+        $prevMin = $minFree
+    } until ($settled -or $sw.Elapsed.TotalSeconds -gt $TimeoutSeconds)
+    $minFree
+}
+
+function Get-ShrinkTestFileSizes {
+    <# .SYNOPSIS Return the data files' allocated and used sizes (MB). #>
+    [CmdletBinding()]
+    param([Parameter(Mandatory)][pscustomobject]$TestDb)
+    Invoke-ShrinkTestSql -Context $TestDb -Database $TestDb.Database -Query @"
+SELECT file_id, name,
+       CAST(size/128.0 AS int) AS alloc_mb,
+       CAST(FILEPROPERTY(name,'SpaceUsed')/128.0 AS int) AS used_mb
+FROM sys.database_files WHERE type_desc = 'ROWS' ORDER BY file_id;
+"@
+}
+
+function Add-ShrinkTestTailSpace {
+    <# .SYNOPSIS Grow each ROWS data file by $AddMB so a TRUNCATEONLY shrink has guaranteed unused space
+       at the tail to reclaim (the drop-created free space is interspersed and may not sit at the end). #>
+    [CmdletBinding()]
+    param([Parameter(Mandatory)][pscustomobject]$TestDb, [int]$AddMB = 48)
+    $sb = [System.Text.StringBuilder]::new()
+    foreach ($f in (Get-ShrinkTestFileSizes -TestDb $TestDb)) {
+        $newSize = [int]$f.alloc_mb + $AddMB
+        [void]$sb.AppendLine("ALTER DATABASE [$($TestDb.Database)] MODIFY FILE (NAME = '$($f.name)', SIZE = ${newSize}MB);")
+    }
+    Invoke-ShrinkTestSql -Context $TestDb -Database $TestDb.Database -Query $sb.ToString() -CommandTimeout 120 | Out-Null
+}
+
+function Open-ShrinkTestBlocker {
+    <# .SYNOPSIS Open a connection that holds an exclusive lock on $TableName inside an open transaction,
+       so a concurrent shrink of that data blocks and cannot finish. Returns the live connection; pass it
+       to Close-ShrinkTestBlocker to roll back and release. #>
+    [CmdletBinding()][OutputType([Microsoft.Data.SqlClient.SqlConnection])]
+    param([Parameter(Mandatory)][pscustomobject]$TestDb, [string]$TableName = 'dbo.t2')
+    $conn = New-ShrinkTestConnection -ServerInstance $TestDb.ServerInstance -Database $TestDb.Database `
+        -Auth $TestDb.Auth -SqlLogin $TestDb.SqlLogin -SqlPassword $TestDb.SqlPassword `
+        -TrustServerCertificate ([bool]$TestDb.TrustServerCertificate)
+    $cmd = $conn.CreateCommand()
+    $cmd.CommandText = "BEGIN TRAN; SELECT TOP (1) 1 FROM $TableName WITH (TABLOCKX, HOLDLOCK);"
+    $cmd.CommandTimeout = 30
+    $cmd.ExecuteNonQuery() | Out-Null
+    $cmd.Dispose()
+    $conn
+}
+
+function Close-ShrinkTestBlocker {
+    <# .SYNOPSIS Roll back the blocking transaction and dispose the connection from Open-ShrinkTestBlocker. #>
+    [CmdletBinding()]
+    param([Microsoft.Data.SqlClient.SqlConnection]$Connection)
+    if (-not $Connection) { return }
+    try { $c = $Connection.CreateCommand(); $c.CommandText = 'IF @@TRANCOUNT > 0 ROLLBACK;'; $c.ExecuteNonQuery() | Out-Null; $c.Dispose() } catch { }
+    try { $Connection.Dispose() } catch { }
+}
+
+function Remove-ShrinkTestDatabase {
+    <# .SYNOPSIS Drop the test database and delete its files (box). #>
+    [CmdletBinding()]
+    param([Parameter(Mandatory)][pscustomobject]$TestDb)
+    try {
+        if ($TestDb.Engine -eq 5) {
+            Invoke-ShrinkTestSql -Context $TestDb -Database master -Query "DROP DATABASE IF EXISTS [$($TestDb.Database)];" -CommandTimeout 120 | Out-Null
+        }
+        else {
+            Invoke-ShrinkTestSql -Context $TestDb -Database master -Query "IF DB_ID('$($TestDb.Database)') IS NOT NULL BEGIN ALTER DATABASE [$($TestDb.Database)] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE [$($TestDb.Database)]; END;" | Out-Null
+        }
+    }
+    catch { Write-Warning "Failed to drop [$($TestDb.Database)]: $($_.Exception.Message)" }
+    if ($TestDb.DataDir -and (Test-Path $TestDb.DataDir)) { Remove-Item -Recurse -Force $TestDb.DataDir -ErrorAction SilentlyContinue }
+}
+
+Export-ModuleMember -Function Get-ShrinkTestServer, Get-ShrinkTestEngineEdition, New-ShrinkTestDatabase, Wait-ShrinkFreeSpaceSettled, Get-ShrinkTestFileSizes, Add-ShrinkTestTailSpace, Open-ShrinkTestBlocker, Close-ShrinkTestBlocker, Remove-ShrinkTestDatabase

From 63c50b1d417c6794ffa9c9eb9ae3bccd4d9fe5c6 Mon Sep 17 00:00:00 2001
From: Dimitri Furman <dfurman@microsoft.com>
Date: Wed, 15 Jul 2026 18:05:02 -0400
Subject: [PATCH 2/2] Address review feedback; report reclaimable space left at
 end of run

Add a PSScriptInfo block (version 1.0.0) to ShrinkDriver.ps1 for script version metadata.
---
 .../shrink/shrink-driver/src/ShrinkDriver.ps1 | 81 +++++++++++++------
 .../tests/ShrinkDriver.Integration.Tests.ps1  |  8 +-
 .../tests/ShrinkDriver.Unit.Tests.ps1         | 30 +++----
 3 files changed, 76 insertions(+), 43 deletions(-)

diff --git a/samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1 b/samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1
index 1c4ff83608..7bcdf07ab3 100644
--- a/samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1
+++ b/samples/features/shrink/shrink-driver/src/ShrinkDriver.ps1
@@ -1,4 +1,16 @@
-#Requires -Version 7.0
+<#PSScriptInfo
+.VERSION 1.0.0
+.GUID 1b801c08-f374-45df-ba3e-34d9983e9133
+.AUTHOR Microsoft
+.COMPANYNAME Microsoft
+.COPYRIGHT (c) Microsoft Corporation. Licensed under the MIT License.
+.TAGS SQL SQLServer AzureSQL DBCC SHRINKFILE shrink maintenance
+.LICENSEURI https://github.com/microsoft/sql-server-samples/blob/master/license.txt
+.PROJECTURI https://github.com/microsoft/sql-server-samples
+.RELEASENOTES
+Initial version.
+#>
+
 <#
 .SYNOPSIS
   Loads Invoke-ShrinkDriver, a command that reclaims allocated but unused space from
@@ -17,6 +29,8 @@
   Run 'Get-Help Invoke-ShrinkDriver -Full' for the description, parameters, and examples.
 #>
 
+#Requires -Version 7.0
+
 Set-StrictMode -Version Latest
 
 function Invoke-ShrinkDriver {
@@ -186,7 +200,7 @@ function Invoke-ShrinkDriver {
     $useColor = [string]::IsNullOrEmpty($env:NO_COLOR)
     function Write-ShrinkLog {
         param([string]$Message, [string]$Level = 'INFO')
-        $stamp = (Get-Date).ToString('yyyy-MM-dd HH:mm:ss')
+        $stamp = (Get-Date).ToString('yyyy-MM-dd HH:mm:ss zzz')
         $line = '{0} [{1}] {2}' -f $stamp, $Level, $Message
         [System.Threading.Monitor]::Enter($logLock)
         try {
@@ -200,9 +214,9 @@ function Invoke-ShrinkDriver {
                     'ERROR' { 'Red' }
                     'WARN' { 'Yellow' }
                     default {
-                        if ($Message -match '^-{3,}') { 'Cyan' }                                          # section dividers/headers
-                        elseif ($Message -match '(Grew|Gave up|Partly shrunk)\s*:\s*[1-9]') { 'Yellow' }  # non-zero problem outcomes
-                        elseif ($Message -match '(Shrunk|Repacked)\s*:\s*[1-9]') { 'Green' }               # non-zero successful outcomes
+                        if ($Message -match '^-{3,}') { 'Cyan' } # section dividers/headers
+                        elseif ($Message -match '(Grew|Gave up|Partly shrunk)\s*:\s*[1-9]') { 'Yellow' } # non-zero problem outcomes
+                        elseif ($Message -match '(Shrunk|Repacked)\s*:\s*[1-9]') { 'Green' } # non-zero successful outcomes
                         else { $null }
                     }
                 }
@@ -472,6 +486,7 @@ SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition,
             DbUsedMB      = $usedSum
             DbAllocatedMB = $allocSum
             Counts        = (Get-ShrinkBucketCounts -Buckets @())
+            EligibleRemaining = 0
             Files         = @()
         }
     }
@@ -562,7 +577,7 @@ SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition,
                     # shown separately in the database-total section.
                     $shared.Sessions[$workerId].Spid = $newSpid
                     $shared.Sessions[$workerId].State = 'Shrinking'
-                    $shared.Sessions[$workerId].ConnectTime = (Get-Date)
+                    $shared.Sessions[$workerId].ConnectTime = [System.Diagnostics.Stopwatch]::GetTimestamp()
                     Emit "reconnected on attempt $try (session ID $newSpid)"
                     return $newConn
                 }
@@ -578,7 +593,7 @@ SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition,
         $conn = New-WConn
         $spidCmd = $conn.CreateCommand(); $spidCmd.CommandText = 'SELECT @@SPID'
         $spid = [int]$spidCmd.ExecuteScalar(); $spidCmd.Dispose()
-        $shared.Sessions[$workerId] = @{ Spid = $spid; Command = $null; FileId = $null; State = 'Idle'; ConnectTime = (Get-Date); RequestSeq = 0 }
+        $shared.Sessions[$workerId] = @{ Spid = $spid; Command = $null; FileId = $null; State = 'Idle'; ConnectTime = [System.Diagnostics.Stopwatch]::GetTimestamp(); RequestSeq = 0 }
         Emit "Connected (session ID $spid)"
 
         try {
@@ -862,8 +877,11 @@ SELECT CAST(SERVERPROPERTY('EngineEdition') AS int) AS engine_edition,
     }
 
     # ----- monitor loop -----
-    $startTime = Get-Date
-    $deadline = if ($null -ne $MaxRuntimeSecondsOverride) { $startTime.AddSeconds([int]$MaxRuntimeSecondsOverride) } elseif ($null -ne $MaxRuntimeMinutes) { $startTime.AddMinutes([int]$MaxRuntimeMinutes) } else { $null }
+    # Drive all run-time and interval math from a monotonic clock so a wall-clock change mid-run (a
+    # DST transition or an NTP/manual adjustment) cannot make the run-time limit fire early or late,
+    # or yield a negative elapsed.
+    $runClock = [System.Diagnostics.Stopwatch]::StartNew()
+    $limitSeconds = if ($null -ne $MaxRuntimeSecondsOverride) { [double]$MaxRuntimeSecondsOverride } elseif ($null -ne $MaxRuntimeMinutes) { [double]$MaxRuntimeMinutes * 60 } else { $null }
     $prev = @{}; $stuckState = @{}
 
     function Write-StatusReport {
@@ -901,9 +919,10 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
         foreach ($sess in $shared.Sessions.GetEnumerator() | Sort-Object { $_.Key }) {
             $workerId = $sess.Key; $s = $sess.Value
             $seq = [int]$s.RequestSeq
-            # Elapsed is the worker's wall-clock time on its current connection (it resets when the
-            # worker reconnects). The run-wide elapsed since script start is in the database-total section.
-            $sessElapsedS = if ($s.ConnectTime) { [int]((Get-Date) - [datetime]$s.ConnectTime).TotalSeconds } else { $null }
+            # Elapsed is the worker's time on its current connection (it resets when the worker
+            # reconnects). ConnectTime is a monotonic timestamp; the run-wide elapsed since script
+            # start is in the database-total section.
+            $sessElapsedS = if ($s.ConnectTime) { [int](([System.Diagnostics.Stopwatch]::GetTimestamp() - [long]$s.ConnectTime) / [System.Diagnostics.Stopwatch]::Frequency) } else { $null }
             $row = $rows | Where-Object Spid -eq $s.Spid | Select-Object -First 1
             if (-not $row) {
                 $statusData.Add([pscustomobject]@{
@@ -937,7 +956,7 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
                 })
 
             if (-not $stuckState.ContainsKey($s.Spid)) { $stuckState[$s.Spid] = @{ Blocker = 0; Cpu = 0; Reads = 0; BlockerSince = $null; NoProgressSince = $null } }
-            $st = Update-ShrinkStuckState -State $stuckState[$s.Spid] -Blocker $row.Blocker -Cpu $row.Cpu -Reads $row.Reads -Now (Get-Date) -WindowSec $StuckWindowSeconds
+            $st = Update-ShrinkStuckState -State $stuckState[$s.Spid] -Blocker $row.Blocker -Cpu $row.Cpu -Reads $row.Reads -NowSeconds $runClock.Elapsed.TotalSeconds -WindowSec $StuckWindowSeconds
             if ($st.IsStuck -and $s.Command) {
                 $why = if ($st.BlockerStuck -and $row.Blocker) { "blocked by session $($row.Blocker)" } else { 'no CPU or read progress' }
                 Write-ShrinkLog ("worker {0} session ID {1} stuck ({2}) for >= {3}s: cancelling command." -f $workerId, $s.Spid, $why, $StuckWindowSeconds) 'WARN'
@@ -981,7 +1000,7 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
         $c = Get-ShrinkBucketCounts -Buckets $buckets
         Write-ShrinkLog '---- database total ----'
         Format-ShrinkKeyValueTable -Rows (Get-ShrinkTotalsRows `
-                -RunTime (Format-ShrinkDuration -TimeSpan ((Get-Date) - $startTime)) `
+                -RunTime (Format-ShrinkDuration -TimeSpan $runClock.Elapsed) `
                 -Used (Format-ShrinkSize $dbUsedMb) -Allocated (Format-ShrinkSize $dbAllocMb) -Counts $c) |
             ForEach-Object { Write-ShrinkLog $_ }
     }
@@ -990,7 +1009,7 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
     # promptly, but run the heavier per-file status report only every StatusIntervalSeconds
     # (with the first one shortly after startup so progress shows without a long initial wait).
     $pollSeconds = [Math]::Max(1, [Math]::Min(2, $StatusIntervalSeconds))
-    $nextReport = (Get-Date).AddSeconds([Math]::Min(15, $StatusIntervalSeconds))
+    $nextReportAtS = [double][Math]::Min(15, $StatusIntervalSeconds)
     try {
         while ($true) {
             $evt = ''
@@ -1017,7 +1036,7 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
                     }
                 }
             }
-            if ((Get-Date) -ge $nextReport) {
+            if ($runClock.Elapsed.TotalSeconds -ge $nextReportAtS) {
                 # The status report reads through the control connection; if the server dropped it
                 # (e.g. a restart), reopen it and skip just this report rather than failing the run.
                 try {
@@ -1028,10 +1047,10 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
                     Write-ShrinkLog ("Status report skipped (control connection issue): {0}" -f $_.Exception.Message.Split([Environment]::NewLine)[0]) 'WARN'
                     try { $control = Get-ShrinkLiveControl $control } catch { Write-ShrinkLog ("Control reconnect failed; will retry at the next report: {0}" -f $_.Exception.Message.Split([Environment]::NewLine)[0]) 'WARN' }
                 }
-                $nextReport = (Get-Date).AddSeconds($StatusIntervalSeconds)
+                $nextReportAtS = $runClock.Elapsed.TotalSeconds + $StatusIntervalSeconds
             }
             if (-not ($workers | Where-Object { -not $_.Handle.IsCompleted })) { Write-ShrinkLog 'All workers finished.'; break }
-            if ($deadline -and (Get-Date) -ge $deadline -and -not $shared.Stop) {
+            if ($null -ne $limitSeconds -and $runClock.Elapsed.TotalSeconds -ge $limitSeconds -and -not $shared.Stop) {
                 Write-ShrinkLog 'Run time limit reached: stopping and recording each in-flight file''s current state.' 'WARN'
                 $shared.StopReason = 'Timeout'
                 $shared.Stop = $true
@@ -1049,14 +1068,20 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
         # Flush any worker events that arrived after the last poll, then write a single final summary.
         $evt = ''
         while ($shared.Events.TryDequeue([ref]$evt)) { Write-ShrinkLog $evt 'EVENT' }
-        $elapsed = Format-ShrinkDuration -TimeSpan ((Get-Date) - $startTime)
+        $elapsed = Format-ShrinkDuration -TimeSpan $runClock.Elapsed
         # The final totals need a live control connection; if the server dropped it (e.g. a restart),
         # try once to reopen, but never let that stop us from writing the outcome summary.
         $dbUsedMb = $null; $dbAllocMb = $null
+        # After shrinking, re-check which data files still have at least MinReclaimMB of reclaimable
+        # space. A file may have been shrunk only partly or skipped for reasons that are often transient
+        # (it grew while being shrunk, or was blocked), and files can also become eligible during a long
+        # run; in either case a later run can frequently reclaim more. This is advisory only.
+        $remainingEligible = @()
         try {
             $control = Get-ShrinkLiveControl $control
             $tot = Get-ShrinkDatabaseTotals -Conn $control
             $dbUsedMb = $tot.Used; $dbAllocMb = $tot.Alloc
+            $remainingEligible = @(Get-EligibleFiles -Conn $control | Where-Object { Test-ShrinkWorthwhile -AllocatedMB $_.AllocatedMB -UsedMB $_.UsedMB -FloorMB $floorMB -MinReclaimMB $minReclaimMB })
         } catch { Write-ShrinkLog ("Could not read final database totals: {0}" -f $_.Exception.Message.Split([Environment]::NewLine)[0]) 'WARN' }
         # Reconcile: any eligible file that never reached a terminal state (e.g. left unprocessed after
         # an unrecoverable outage, or never started) is recorded as NotProcessed, so the summary reflects
@@ -1076,6 +1101,11 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
                 -Allocated $(if ($null -ne $dbAllocMb) { Format-ShrinkSize $dbAllocMb } else { '(unavailable)' }) -Counts $c) |
             ForEach-Object { Write-ShrinkLog $_ }
         foreach ($r in $shared.Completed.GetEnumerator() | Sort-Object { [int]$_.Key }) { if ($r.Value.Reason) { Write-ShrinkLog ("  file {0} [{1}]: {2}" -f $r.Key, $r.Value.Bucket, $r.Value.Reason) } }
+        if ($remainingEligible.Count -gt 0) {
+            $reclRemainMb = [long]0
+            foreach ($f in $remainingEligible) { $reclRemainMb += (Get-ShrinkReclaimableMB -AllocatedMB $f.AllocatedMB -UsedMB $f.UsedMB -FloorMB $floorMB) }
+            Write-ShrinkLog ("{0} data file(s) still have reclaimable space ({1} total). A partial or skipped shrink can be due to transient conditions (such as concurrent growth or blocking), so running shrink again might reclaim more." -f $remainingEligible.Count, (Format-ShrinkSize $reclRemainMb))
+        }
         Write-ShrinkLog '-------------------------------------------------'
         # Structured result for programmatic callers / tests (the log/console is unchanged).
         $runResult = [pscustomobject]@{
@@ -1085,6 +1115,7 @@ FROM sys.dm_exec_requests r WHERE r.session_id IN ($inList);
             DbUsedMB      = $dbUsedMb
             DbAllocatedMB = $dbAllocMb
             Counts        = $c
+            EligibleRemaining = $remainingEligible.Count
             Files         = @($shared.Completed.GetEnumerator() | Sort-Object { [int]$_.Key } | ForEach-Object { [pscustomobject]@{ FileId = [int]$_.Key; Bucket = $_.Value.Bucket; Reason = $_.Value.Reason } })
         }
         try { $control.Close() } catch {}
@@ -1562,25 +1593,27 @@ function Update-ShrinkStuckState {
         [int]$Blocker = 0,
         [long]$Cpu = 0,
         [long]$Reads = 0,
-        [datetime]$Now = (Get-Date),
+        [double]$NowSeconds = ([System.Diagnostics.Stopwatch]::GetTimestamp() / [double][System.Diagnostics.Stopwatch]::Frequency),
         [int]$WindowSec = 300
     )
+    # $NowSeconds is a monotonic seconds value (e.g. the run stopwatch's elapsed seconds), not wall
+    # clock, so the elapsed-time comparisons below are immune to a clock change mid-run.
     # Blocker streak: how long the same non-zero blocking session has persisted. Cleared when there is
     # no blocker; restarted when the blocking session changes.
     if (-not $Blocker) {
         $State.BlockerSince = $null
     }
     elseif ($State.Blocker -ne $Blocker -or $null -eq $State.BlockerSince) {
-        $State.BlockerSince = $Now
+        $State.BlockerSince = $NowSeconds
     }
     # No-progress streak: how long neither CPU nor reads have changed. Any change - including a
     # per-request counter reset, which signals a new step - counts as progress and restarts the streak.
     if ($State.Cpu -ne $Cpu -or $State.Reads -ne $Reads -or $null -eq $State.NoProgressSince) {
-        $State.NoProgressSince = $Now
+        $State.NoProgressSince = $NowSeconds
     }
 
-    $blockerStuck = ($null -ne $State.BlockerSince) -and (($Now - [datetime]$State.BlockerSince).TotalSeconds -ge $WindowSec)
-    $noProgressStuck = ($null -ne $State.NoProgressSince) -and (($Now - [datetime]$State.NoProgressSince).TotalSeconds -ge $WindowSec)
+    $blockerStuck = ($null -ne $State.BlockerSince) -and (($NowSeconds - [double]$State.BlockerSince) -ge $WindowSec)
+    $noProgressStuck = ($null -ne $State.NoProgressSince) -and (($NowSeconds - [double]$State.NoProgressSince) -ge $WindowSec)
     $isStuck = [bool]($blockerStuck -or $noProgressStuck)
 
     $State.Blocker = $Blocker
diff --git a/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1 b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1
index d71c0935e5..7f6e26e0c0 100644
--- a/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1
+++ b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Integration.Tests.ps1
@@ -254,6 +254,12 @@ Describe 'ShrinkDriver integration' -Tag 'Integration' -Skip:(-not $server) {
             $res.Files.Count | Should -BeGreaterThan 0
             ($res.Counts.Interrupted + $res.Counts.PartlyShrunk + $res.Counts.NotProcessed) | Should -BeGreaterThan 0
         }
+
+        It 'reports data files that still have reclaimable space to reclaim on a re-run' {
+            # The blocked and unprocessed files were not fully shrunk, so an end-of-run re-check finds
+            # space still reclaimable and reports it for a follow-up run.
+            $res.EligibleRemaining | Should -BeGreaterThan 0
+        }
     }
 
     Context 'Worker reconnect after a dropped connection' -Skip:(-not $isBoxEngine) {
@@ -273,7 +279,7 @@ Describe 'ShrinkDriver integration' -Tag 'Integration' -Skip:(-not $server) {
                 while ((Get-Date) -lt $deadline -and $kills -lt 2) {
                     try {
                         $r = Invoke-Sqlcmd -ServerInstance $serverInstance -Database $database -TrustServerCertificate -ErrorAction Stop `
-                            -Query "SELECT TOP (1) session_id AS spid FROM sys.dm_exec_sessions WHERE program_name LIKE 'ShrinkDriver-w%'"
+                            -Query "SELECT TOP (1) session_id AS spid FROM sys.dm_exec_sessions WHERE program_name LIKE 'ShrinkDriver-w%' AND database_id = DB_ID()"
                         if ($r -and $null -ne $r.spid) {
                             Invoke-Sqlcmd -ServerInstance $serverInstance -Database $database -TrustServerCertificate -ErrorAction Stop -Query "KILL $($r.spid)"
                             $kills++
diff --git a/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1 b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1
index 143e99dc0b..35376c119c 100644
--- a/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1
+++ b/samples/features/shrink/shrink-driver/tests/ShrinkDriver.Unit.Tests.ps1
@@ -419,39 +419,33 @@ Describe 'Get-ShrinkDeltaWithReset' {
 Describe 'Update-ShrinkStuckState' {
     It 'fires when the same non-zero blocker persists for the window, even while CPU advances' {
         $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
-        $t0 = Get-Date
-        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300).IsStuck | Should -BeFalse
-        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 999 -Reads 999 -Now $t0.AddSeconds(310) -WindowSec 300).IsStuck | Should -BeTrue
+        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -NowSeconds 0 -WindowSec 300).IsStuck | Should -BeFalse
+        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 999 -Reads 999 -NowSeconds 310 -WindowSec 300).IsStuck | Should -BeTrue
     }
     It 'fires when neither CPU nor reads advance for the window, with no blocker' {
         $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
-        $t0 = Get-Date
-        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300).IsStuck | Should -BeFalse
-        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -Now $t0.AddSeconds(310) -WindowSec 300).IsStuck | Should -BeTrue
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -NowSeconds 0 -WindowSec 300).IsStuck | Should -BeFalse
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -NowSeconds 310 -WindowSec 300).IsStuck | Should -BeTrue
     }
     It 'does not fire while CPU or reads keep advancing and there is no blocker' {
         $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
-        $t0 = Get-Date
-        Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300 | Out-Null
-        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 20 -Reads 30 -Now $t0.AddSeconds(400) -WindowSec 300).IsStuck | Should -BeFalse
+        Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 10 -Reads 10 -NowSeconds 0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 20 -Reads 30 -NowSeconds 400 -WindowSec 300).IsStuck | Should -BeFalse
     }
     It 'treats a per-request counter reset as progress' {
         $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
-        $t0 = Get-Date
-        Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 500 -Reads 500 -Now $t0 -WindowSec 300 | Out-Null
-        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 5 -Reads 5 -Now $t0.AddSeconds(310) -WindowSec 300).IsStuck | Should -BeFalse
+        Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 500 -Reads 500 -NowSeconds 0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 0 -Cpu 5 -Reads 5 -NowSeconds 310 -WindowSec 300).IsStuck | Should -BeFalse
     }
     It 'restarts the blocker streak when the blocker changes' {
         $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
-        $t0 = Get-Date
-        Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300 | Out-Null
-        (Update-ShrinkStuckState -State $state -Blocker 77 -Cpu 20 -Reads 20 -Now $t0.AddSeconds(400) -WindowSec 300).IsStuck | Should -BeFalse
+        Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -NowSeconds 0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 77 -Cpu 20 -Reads 20 -NowSeconds 400 -WindowSec 300).IsStuck | Should -BeFalse
     }
     It 'does not fire within the window' {
         $state = @{ Blocker=$null; Cpu=0; Reads=0; BlockerSince=$null; NoProgressSince=$null }
-        $t0 = Get-Date
-        Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0 -WindowSec 300 | Out-Null
-        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -Now $t0.AddSeconds(120) -WindowSec 300).IsStuck | Should -BeFalse
+        Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -NowSeconds 0 -WindowSec 300 | Out-Null
+        (Update-ShrinkStuckState -State $state -Blocker 55 -Cpu 10 -Reads 10 -NowSeconds 120 -WindowSec 300).IsStuck | Should -BeFalse
     }
 }