@rightkit/release 0.2.150 → 0.2.153

package/msix-repair-guard.ps1

@@ -0,0 +1,356 @@
+# RightKit MSIX repair guard (canonical source: rightkit/packages/release/msix-repair-guard.ps1). ASCII only; Windows PowerShell 5.1 compatible.
+#
+# Why this exists: cancelling an MSIX update while Windows registers it can leave the OLD package
+# "Modified, NeedsRemediation" (event 751: "Windows failed to undo changes ... The package needs to be reinstalled").
+# A package in that state cannot be launched, so nothing inside the package can repair it. This script lives OUTSIDE the
+# package (the app writes it to %LOCALAPPDATA%\<AppName>\repair\ on every normal launch) and is run by a per-user scheduled
+# task `<PFN>-Repair` (no admin) on event 751 in Microsoft-Windows-AppXDeploymentServer/Operational, at logon, and at a
+# one-shot retry time after a failed repair.
+#
+#   msix-repair-guard.ps1 -Install -Pfn <family> [-Feed <.appinstaller uri>]   register/refresh the task and write guard.json
+#   msix-repair-guard.ps1                                                      (task action) repair if needed, clean up if uninstalled
+#
+# Repair order: `Add-AppxPackage -AppInstallerFile <feed>` (known-good), then `Add-AppxPackage -Path <msix>` (the msix is downloaded
+# first and its manifest identity checked). Every decision is logged to repair.log next to this script; every run also writes a
+# machine-readable last-result.json (status, code, time, detail), because the task runs under `conhost --headless` and hides exit codes.
+#
+# Exit codes (also in last-result.json): 0 healthy / repaired / cleaned up / another run active, 1 repair failed (a retry is scheduled),
+# 2 guard misconfigured or refused (guard.json or an install input failed validation), 3 no install source known, 4 unhandled error
+# (logged; a retry is scheduled).
+#
+# Retry: after a failed repair (exit 1 or 4) the script gives the task a one-shot time trigger at +2, +5, +15, +60 minutes and then
+# hourly, for at most 24 hours from the first failure; the trigger is removed on success, when the package is healthy, or when the
+# app is uninstalled. State: retry.json. A later logon or event 751 run still starts a repair at any time.
+#
+# Uninstall cleanup: a run that finds the package absent (twice, 10 s apart) removes this folder and the task. It runs at the next
+# logon, the next event 751, or the next retry tick; Windows has no "package removed" trigger for a per-user task.
+#
+# Hardening: feed and msix URIs must be https, or http to a loopback host (a local test feed). A feed or msix whose identity (Name,
+# Publisher) differs from the installed package is refused and never installed. guard.json must name this folder's task.
+#
+# Requirement: the app's data directory must be physical (MSIX fileSystemWrite virtualization disabled), otherwise the packaged app
+# writes this folder into its private LocalCache and the task cannot see it.
+[CmdletBinding()]
+param([switch]$Install, [string]$Pfn = '', [string]$Feed = '')
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'   # Windows PowerShell 5.1 renders a progress bar per downloaded chunk: a 30 MB Invoke-WebRequest -OutFile then takes minutes
+$GuardVersion = 2
+$Dir = Split-Path -Parent $PSCommandPath
+$LogPath = Join-Path $Dir 'repair.log'
+$ConfigPath = Join-Path $Dir 'guard.json'
+$RetryPath = Join-Path $Dir 'retry.json'
+$AttemptPath = Join-Path $Dir 'install-attempt.json'
+$ResultPath = Join-Path $Dir $(if ($Install) { 'install-result.json' } else { 'last-result.json' })
+$Mode = $(if ($Install) { 'install' } else { 'repair' })
+$RetryDelaysMinutes = @(2, 5, 15, 60)   # then hourly
+$RetryWindowHours = 24
+$PfnPattern = '^[A-Za-z0-9][A-Za-z0-9.\-]*_[a-z0-9]{13}$'
+$script:Ctx = ''
+
+function Log([string]$m) {
+    try {
+        if ((Test-Path -LiteralPath $LogPath) -and ((Get-Item -LiteralPath $LogPath).Length -gt 262144)) { Move-Item -LiteralPath $LogPath -Destination ($LogPath + '.old') -Force }
+        Add-Content -LiteralPath $LogPath -Value ((Get-Date).ToString('yyyy-MM-ddTHH:mm:ss.fffzzz') + ' [' + $Mode + '] ' + $m)
+    } catch { }
+}
+function Write-Json([string]$path, $obj) {
+    try {
+        $tmp = $path + '.tmp'
+        [IO.File]::WriteAllText($tmp, ($obj | ConvertTo-Json), (New-Object Text.UTF8Encoding($false)))
+        Move-Item -LiteralPath $tmp -Destination $path -Force
+    } catch { Log ('could not write ' + $path + ': ' + $_.Exception.Message) }
+}
+function Write-Result([string]$status, [int]$code, [string]$detail) {
+    $r = [ordered]@{ status = $status; code = $code; mode = $Mode; timeUtc = (Get-Date).ToUniversalTime().ToString('o'); guardVersion = $GuardVersion; detail = $detail }
+    $st = Read-Json $RetryPath
+    if ($st -and $st.nextEpoch) { $r.nextRetryUtc = ([datetime]'1970-01-01T00:00:00Z').ToUniversalTime().AddSeconds([double]$st.nextEpoch).ToString('o'); $r.retryAttempt = [int]$st.attempt }
+    Write-Json $ResultPath $r
+}
+function Finish([string]$status, [int]$code, [string]$detail) {
+    Log ($status.ToUpper() + ' (code ' + $code + '): ' + $detail)
+    Write-Result $status $code $detail
+    exit $code
+}
+function Read-Json([string]$path) { try { return (Get-Content -LiteralPath $path -Raw -ErrorAction Stop | ConvertFrom-Json) } catch { return $null } }
+function Read-Config { return (Read-Json $ConfigPath) }
+
+# ------------------------------------------------------------------ scheduled task (shared by install and the retry logic)
+function Get-TaskXml([string]$family, $retryLocal) {
+    $id = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $esc = { param($s) [Security.SecurityElement]::Escape([string]$s) }
+    $sub = '<QueryList><Query Id="0" Path="Microsoft-Windows-AppXDeploymentServer/Operational"><Select Path="Microsoft-Windows-AppXDeploymentServer/Operational">*[System[(EventID=751)]]</Select></Query></QueryList>'
+    $taskArgs = '--headless powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "' + $PSCommandPath + '"'
+    $retryXml = ''
+    if ($retryLocal) { $retryXml = '<TimeTrigger><StartBoundary>' + ([datetime]$retryLocal).ToString('yyyy-MM-ddTHH:mm:ss') + '</StartBoundary><Enabled>true</Enabled></TimeTrigger>' }
+    return @"
+<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo><Description>Repair guard for $(& $esc $family): re-adds the app from its App Installer feed when an interrupted update leaves it NeedsRemediation; retries after a failure. Removes itself when the app is uninstalled.</Description></RegistrationInfo>
+  <Triggers>
+    <EventTrigger><Enabled>true</Enabled><Subscription>$(& $esc $sub)</Subscription></EventTrigger>
+    <LogonTrigger><Enabled>true</Enabled><UserId>$(& $esc $id.Name)</UserId></LogonTrigger>
+    $retryXml
+  </Triggers>
+  <Principals><Principal id="Author"><UserId>$(& $esc $id.User.Value)</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>true</Hidden>
+    <ExecutionTimeLimit>PT30M</ExecutionTimeLimit>
+  </Settings>
+  <Actions Context="Author"><Exec><Command>%SystemRoot%\System32\conhost.exe</Command><Arguments>$(& $esc $taskArgs)</Arguments></Exec></Actions>
+</Task>
+"@
+}
+function Register-GuardTask([string]$family, $retryLocal) {
+    [void](Register-ScheduledTask -TaskName ($family + '-Repair') -Xml (Get-TaskXml $family $retryLocal) -Force)
+}
+function Get-RetryLocal {
+    $st = Read-Json $RetryPath
+    if ($st -and $st.nextEpoch) { return ([datetime]'1970-01-01T00:00:00Z').ToUniversalTime().AddSeconds([double]$st.nextEpoch).ToLocalTime() }
+    return $null
+}
+
+# ------------------------------------------------------------------ retry state (repair mode)
+function Clear-Retry([string]$family) {
+    if (-not (Test-Path -LiteralPath $RetryPath)) { return }
+    try { Remove-Item -LiteralPath $RetryPath -Force } catch { }
+    try { Register-GuardTask $family $null; Log 'retry cleared (task has no one-shot trigger)' } catch { Log ('could not clear the retry trigger: ' + $_.Exception.Message) }
+}
+function Set-Retry([string]$family, [string]$why) {
+    $epoch0 = [datetime]'1970-01-01T00:00:00Z'
+    $now = [datetime]::UtcNow
+    $nowEpoch = [math]::Floor(($now - $epoch0.ToUniversalTime()).TotalSeconds)
+    $st = Read-Json $RetryPath
+    $attempt = 1; $first = $nowEpoch
+    if ($st -and $st.firstFailureEpoch -and (($nowEpoch - [double]$st.firstFailureEpoch) -lt ($RetryWindowHours * 3600))) { $attempt = [int]$st.attempt + 1; $first = [double]$st.firstFailureEpoch }
+    $delay = $(if ($attempt -le $RetryDelaysMinutes.Count) { $RetryDelaysMinutes[$attempt - 1] } else { 60 })
+    $next = $nowEpoch + ($delay * 60)
+    if (($next - $first) -gt ($RetryWindowHours * 3600)) {
+        Write-Json $RetryPath ([ordered]@{ attempt = $attempt; firstFailureEpoch = $first; gaveUp = $true; reason = $why })
+        try { Register-GuardTask $family $null } catch { }
+        Log ('retry window of ' + $RetryWindowHours + ' h used up after ' + ($attempt - 1) + ' retries; no further automatic retry (next logon / event 751 starts again)')
+        return
+    }
+    Write-Json $RetryPath ([ordered]@{ attempt = $attempt; firstFailureEpoch = $first; nextEpoch = $next; delayMinutes = $delay; reason = $why })
+    $local = $epoch0.ToUniversalTime().AddSeconds($next).ToLocalTime()
+    try { Register-GuardTask $family $local; Log ('retry ' + $attempt + ' scheduled in ' + $delay + ' min at ' + $local.ToString('s')) } catch { Log ('could not schedule the retry: ' + $_.Exception.Message) }
+}
+
+# ------------------------------------------------------------------ package state
+function Get-Family([string]$family) {
+    $name = $family.Substring(0, $family.LastIndexOf('_'))
+    return @(Get-AppxPackage -Name $name -PackageTypeFilter Main -ErrorAction SilentlyContinue | Where-Object { [string]$_.PackageFamilyName -eq $family })
+}
+function Get-StateText([string]$family) {
+    $p = @(Get-Family $family)
+    if ($p.Count -eq 0) { return 'absent' }
+    return (($p | ForEach-Object { [string]$_.Version + ':' + [string]$_.Status }) -join ',')
+}
+function Test-Healthy([string]$family) {
+    $p = @(Get-Family $family)
+    return ($p.Count -gt 0 -and @($p | Where-Object { [string]$_.Status -ne 'Ok' }).Count -eq 0)
+}
+function Test-AllowedUri([string]$uri) {
+    try {
+        $u = [Uri]$uri
+        if (-not $u.IsAbsoluteUri -or $u.UserInfo) { return $false }
+        if ($u.Scheme -eq 'https') { return $true }
+        if ($u.Scheme -eq 'http' -and $u.IsLoopback) { return $true }
+    } catch { }
+    return $false
+}
+function Same-Text([string]$a, [string]$b) { return ([string]::Equals($a.Trim(), $b.Trim(), [StringComparison]::OrdinalIgnoreCase)) }
+function Test-Identity($expected, [string]$name, [string]$publisher) {
+    if (-not $expected.name -or -not $expected.publisher) { return 'no expected identity recorded' }
+    if (-not (Same-Text $expected.name $name)) { return ('Name ' + $name + ' differs from ' + $expected.name) }
+    if (-not (Same-Text $expected.publisher $publisher)) { return ('Publisher ' + $publisher + ' differs from ' + $expected.publisher) }
+    return ''
+}
+function Get-FeedInfo([string]$feedUri) {
+    $r = Invoke-WebRequest -Uri $feedUri -UseBasicParsing -TimeoutSec 20 -MaximumRedirection 3
+    if (-not (Test-AllowedUri ([string]$r.BaseResponse.ResponseUri))) { throw ('feed redirected to a disallowed uri ' + $r.BaseResponse.ResponseUri) }
+    $text = $r.Content
+    if ($text -is [byte[]]) { $text = [Text.Encoding]::UTF8.GetString($text) }   # a non-text content type returns bytes
+    $x = [xml]($text.TrimStart([char]0xFEFF))
+    $n = $x.GetElementsByTagName('MainPackage') | Select-Object -First 1
+    if (-not $n) { $n = $x.GetElementsByTagName('MainBundle') | Select-Object -First 1 }
+    if (-not $n) { throw 'feed has no MainPackage or MainBundle' }
+    return [pscustomobject]@{ uri = [string]$n.Uri; name = [string]$n.Name; publisher = [string]$n.Publisher; version = [string]$n.Version }
+}
+function Save-Msix([string]$uri, [string]$dest) {
+    $r = Invoke-WebRequest -Uri $uri -UseBasicParsing -TimeoutSec 900 -MaximumRedirection 3 -OutFile $dest -PassThru
+    if (-not (Test-AllowedUri ([string]$r.BaseResponse.ResponseUri))) { throw ('msix redirected to a disallowed uri ' + $r.BaseResponse.ResponseUri) }
+}
+function Get-MsixIdentity([string]$file) {
+    Add-Type -AssemblyName System.IO.Compression.FileSystem
+    $zip = [IO.Compression.ZipFile]::OpenRead($file)
+    try {
+        $entry = $zip.GetEntry('AppxManifest.xml')
+        $kind = 'Package'
+        if (-not $entry) { $entry = $zip.GetEntry('AppxMetadata/AppxBundleManifest.xml'); $kind = 'Bundle' }
+        if (-not $entry) { throw 'no AppxManifest.xml or AppxBundleManifest.xml in the archive' }
+        $sr = New-Object IO.StreamReader($entry.Open())
+        try { $x = [xml]($sr.ReadToEnd().TrimStart([char]0xFEFF)) } finally { $sr.Dispose() }
+        $idn = $x.GetElementsByTagName('Identity') | Select-Object -First 1
+        if (-not $idn) { throw 'manifest has no Identity' }
+        return [pscustomobject]@{ name = [string]$idn.Name; publisher = [string]$idn.Publisher; version = [string]$idn.Version; kind = $kind }
+    } finally { $zip.Dispose() }
+}
+
+# ================================================================== install: register / refresh the task
+if ($Install) {
+    trap { Log ('UNHANDLED ERROR: ' + $_.Exception.Message + ' at line ' + $_.InvocationInfo.ScriptLineNumber); Write-Result 'error' 4 $_.Exception.Message; exit 4 }
+    if (-not $Pfn) { Finish 'misconfigured' 2 'install refused: no -Pfn' }
+    if ($Pfn -notmatch $PfnPattern) { Finish 'refused' 2 ('install refused: -Pfn is not a package family name: ' + $Pfn) }
+    $prev = Read-Config
+    $feedUri = $Feed
+    try {
+        [void][Windows.Management.Deployment.PackageManager, Windows.Management.Deployment, ContentType = WindowsRuntime]
+        $pm = New-Object Windows.Management.Deployment.PackageManager
+        foreach ($x in @($pm.FindPackagesForUser('', $Pfn))) {
+            $ai = $x.GetAppInstallerInfo()
+            if ($ai -and $ai.Uri) { $feedUri = [string]$ai.Uri; break }
+        }
+    } catch { Log ('App Installer info unreadable: ' + $_.Exception.Message) }
+    if (-not $feedUri -and $prev -and $prev.feed) { $feedUri = [string]$prev.feed; Log 'package has no App Installer association; keeping the recorded feed' }
+    $msix = $(if ($prev -and $prev.msix) { [string]$prev.msix } else { '' })
+    if ($feedUri -and -not (Test-AllowedUri $feedUri)) { Finish 'refused' 2 ('install refused: feed uri is not https (or http to loopback): ' + $feedUri) }
+    if ($feedUri) {
+        try {
+            $fi = Get-FeedInfo $feedUri
+            if ($fi.uri) { if (Test-AllowedUri $fi.uri) { $msix = $fi.uri } else { Log ('feed msix uri not recorded (not https): ' + $fi.uri) } }
+        } catch { Log ('feed not readable at install time (' + $feedUri + '): ' + $_.Exception.Message) }
+    } else { Log 'no App Installer feed known: repair can only use a recorded msix uri' }
+    if ($msix -and -not (Test-AllowedUri $msix)) { Finish 'refused' 2 ('install refused: msix uri is not https (or http to loopback): ' + $msix) }
+
+    # expected identity: what is installed now (this run is started by the packaged app), else what was recorded
+    $name = $(if ($prev -and $prev.name) { [string]$prev.name } else { '' })
+    $publisher = $(if ($prev -and $prev.publisher) { [string]$prev.publisher } else { '' })
+    $pk = @(Get-Family $Pfn) | Select-Object -First 1
+    if ($pk) { $name = [string]$pk.Name; $publisher = [string]$pk.Publisher }
+    if (-not $name -or -not $publisher) { Log 'WARNING: package identity (Name, Publisher) unknown; the repair will refuse every source until a launch of the installed app records it' }
+
+    $taskName = $Pfn + '-Repair'
+    try { Register-GuardTask $Pfn (Get-RetryLocal) } catch { Finish 'misconfigured' 2 ('task registration failed: ' + $_.Exception.Message) }
+    $cfg = [ordered]@{ guardVersion = $GuardVersion; pfn = $Pfn; name = $name; publisher = $publisher; feed = $feedUri; msix = $msix; task = $taskName; dir = $Dir; installedUtc = (Get-Date).ToUniversalTime().ToString('o') }
+    [IO.File]::WriteAllText($ConfigPath, ($cfg | ConvertTo-Json), (New-Object Text.UTF8Encoding($false)))
+    try { Remove-Item -LiteralPath $AttemptPath -Force -ErrorAction SilentlyContinue } catch { }
+    Log ('task ' + $taskName + ' registered; identity=' + $name + ' / ' + $publisher + '; feed=' + $(if ($feedUri) { $feedUri } else { '(none)' }) + ' msix=' + $(if ($msix) { $msix } else { '(none)' }))
+    Write-Result 'installed' 0 ('task ' + $taskName + ' registered')
+    exit 0
+}
+
+# ================================================================== repair (task action)
+trap {
+    Log ('UNHANDLED ERROR: ' + $_.Exception.Message + ' at line ' + $_.InvocationInfo.ScriptLineNumber)
+    Write-Result 'error' 4 $_.Exception.Message
+    if ($script:Ctx) { try { Set-Retry $script:Ctx 'unhandled error' } catch { } }
+    exit 4
+}
+$cfg = Read-Config
+if (-not $cfg -or -not $cfg.pfn) { Finish 'misconfigured' 2 'guard.json missing or unreadable; nothing to do' }
+$family = [string]$cfg.pfn
+$feedUri = [string]$cfg.feed
+$msix = [string]$cfg.msix
+if ($family -notmatch $PfnPattern) { Finish 'refused' 2 ('guard.json pfn is not a package family name: ' + $family) }
+if ([string]$cfg.task -ne ($family + '-Repair')) { Finish 'refused' 2 ('guard.json task ' + [string]$cfg.task + ' is not ' + $family + '-Repair') }
+if ((Split-Path -Leaf $Dir) -ne 'repair') { Finish 'refused' 2 ('script folder is not named repair: ' + $Dir) }
+if ($feedUri -and -not (Test-AllowedUri $feedUri)) { Finish 'refused' 2 ('guard.json feed uri is not https (or http to loopback): ' + $feedUri) }
+if ($msix -and -not (Test-AllowedUri $msix)) { Finish 'refused' 2 ('guard.json msix uri is not https (or http to loopback): ' + $msix) }
+$script:Ctx = $family
+$mutex = [Threading.Mutex]::new($false, ('Local\' + $family + '-Repair'))
+if (-not $mutex.WaitOne(0)) { Log 'another repair run is active; exiting (last-result.json left to that run)'; exit 0 }
+$tmpMsix = ''
+try {
+    $state = Get-StateText $family
+    if ($state -eq 'absent') {
+        Start-Sleep -Seconds 10   # an update or reinstall can briefly show no package; require absence twice
+        $state = Get-StateText $family
+    }
+    if ($state -eq 'absent') {
+        # uninstalled: remove the repair folder (never its parent: that holds user data), then the task itself (last: it ends this run)
+        $note = Join-Path $env:TEMP ($family + '-repair-cleanup.log')
+        try { Add-Content -LiteralPath $note -Value ((Get-Date).ToString('o') + ' package ' + $family + ' absent; removing task ' + $cfg.task + ' and ' + $Dir) } catch { }
+        try { Remove-Item -LiteralPath $Dir -Recurse -Force -ErrorAction Stop } catch { try { Add-Content -LiteralPath $note -Value ('folder removal failed: ' + $_.Exception.Message) } catch { } }
+        try { Unregister-ScheduledTask -TaskName ([string]$cfg.task) -Confirm:$false -ErrorAction Stop; Add-Content -LiteralPath $note -Value 'task unregistered' } catch { try { Add-Content -LiteralPath $note -Value ('task removal failed: ' + $_.Exception.Message) } catch { } }
+        exit 0
+    }
+    if (Test-Healthy $family) { Clear-Retry $family; Finish 'healthy' 0 ('package healthy: ' + $state) }
+    Log ('package NOT healthy: ' + $state + '; letting the deployment service settle')
+    Start-Sleep -Seconds 8
+    if (Test-Healthy $family) { Clear-Retry $family; Finish 'healthy' 0 ('package recovered by itself: ' + (Get-StateText $family)) }
+
+    if (-not $feedUri -and -not $msix) { Finish 'no-source' 3 'FAILED: no App Installer feed and no msix uri recorded; cannot repair. Reinstall from the original source or use Settings > Apps > Advanced options > Repair.' }
+    # expected identity: recorded at install; fall back to the (broken) installed registration, which still reports Name and Publisher
+    $expect = [pscustomobject]@{ name = [string]$cfg.name; publisher = [string]$cfg.publisher }
+    if (-not $expect.name -or -not $expect.publisher) {
+        $pk = @(Get-Family $family) | Select-Object -First 1
+        if ($pk) { $expect.name = [string]$pk.Name; $expect.publisher = [string]$pk.Publisher }
+    }
+    if (-not $expect.name -or -not $expect.publisher) {
+        Log 'FAILED: expected package identity unknown; refusing to install anything'
+        Set-Retry $family 'identity unknown'
+        Write-Result 'failed' 1 'expected package identity unknown'
+        exit 1
+    }
+    $why = @()
+    $feedOk = $false
+    if ($feedUri) {
+        $fi = $null
+        try { $fi = Get-FeedInfo $feedUri } catch { Log ('feed unreachable, skipping -AppInstallerFile: ' + $feedUri + ' : ' + $_.Exception.Message); $why += ('feed unreachable: ' + $_.Exception.Message) }
+        if ($fi) {
+            $bad = Test-Identity $expect $fi.name $fi.publisher
+            if (-not $bad -and $fi.uri -and -not (Test-AllowedUri $fi.uri)) { $bad = 'feed msix uri is not https (or http to loopback): ' + $fi.uri }
+            if ($bad) { Log ('REFUSED feed ' + $feedUri + ': ' + $bad); $why += ('feed refused: ' + $bad) }
+            else {
+                $feedOk = $true
+                if ($fi.uri) { $msix = $fi.uri }   # newer than the one recorded
+                Log ('Add-AppxPackage -AppInstallerFile ' + $feedUri + ' (declares ' + $fi.version + ')')
+                try { Add-AppxPackage -AppInstallerFile $feedUri -ErrorAction Stop } catch { Log ('-AppInstallerFile failed: ' + $_.Exception.Message + ' | ' + $_.FullyQualifiedErrorId); $why += ('-AppInstallerFile failed: ' + $_.Exception.Message) }
+                if (Test-Healthy $family) {
+                    $now = @(Get-Family $family) | Select-Object -First 1
+                    $bad = Test-Identity $expect ([string]$now.Name) ([string]$now.Publisher)
+                    if ($bad) { Log ('FAILED: identity mismatch after repair via feed: ' + $bad); $why += ('identity after repair: ' + $bad) }
+                    else { Clear-Retry $family; Finish 'repaired' 0 ('REPAIRED via feed: ' + (Get-StateText $family)) }
+                }
+            }
+        }
+    }
+    if ($msix) {
+        $tmpMsix = Join-Path $env:TEMP ($family + '-repair-' + [guid]::NewGuid().ToString('N') + '.msix')
+        $got = $false
+        try { Log ('downloading ' + $msix); Save-Msix $msix $tmpMsix; $got = $true } catch { Log ('msix unreachable, skipping -Path: ' + $msix + ' : ' + $_.Exception.Message); $why += ('msix unreachable: ' + $_.Exception.Message) }
+        if ($got) {
+            $mi = $null
+            try { $mi = Get-MsixIdentity $tmpMsix } catch { Log ('REFUSED msix: corrupt or unreadable package: ' + $_.Exception.Message); $why += ('msix corrupt: ' + $_.Exception.Message) }
+            if ($mi) {
+                $bad = Test-Identity $expect $mi.name $mi.publisher
+                if ($bad) { Log ('REFUSED msix ' + $msix + ': ' + $bad); $why += ('msix refused: ' + $bad) }
+                else {
+                    Log ('Add-AppxPackage -Path ' + $msix + ' (' + $mi.kind + ' ' + $mi.version + ')')
+                    try { Add-AppxPackage -Path $tmpMsix -ErrorAction Stop } catch { Log ('-Path failed: ' + $_.Exception.Message + ' | ' + $_.FullyQualifiedErrorId); $why += ('-Path failed: ' + $_.Exception.Message) }
+                    if (Test-Healthy $family) {
+                        $now = @(Get-Family $family) | Select-Object -First 1
+                        $bad = Test-Identity $expect ([string]$now.Name) ([string]$now.Publisher)
+                        if ($bad) { Log ('FAILED: identity mismatch after repair via msix: ' + $bad); $why += ('identity after repair: ' + $bad) }
+                        else { Clear-Retry $family; Finish 'repaired' 0 ('REPAIRED via msix uri: ' + (Get-StateText $family)) }
+                    }
+                }
+            }
+        }
+    } else { $why += 'no msix uri recorded' }
+    $detail = 'FAILED: package still ' + (Get-StateText $family) + '. Reasons: ' + ($why -join ' | ')
+    Set-Retry $family 'repair failed'
+    Write-Result 'failed' 1 $detail
+    Log ($detail + '. A retry is scheduled (see retry.json); manual: Settings > Apps > Advanced options > Repair.')
+    exit 1
+} finally {
+    if ($tmpMsix) { try { Remove-Item -LiteralPath $tmpMsix -Force -ErrorAction SilentlyContinue } catch { } }
+    try { $mutex.ReleaseMutex() } catch { }
+}

package/notarize-macos.mjs

@@ -5,14 +5,15 @@ import { notarizeMacosArtifact } from "./macos-notarization.mjs";
 
 const args = process.argv.slice(2);
 const dryRun = args.includes("--dry-run");
+const noStaple = args.includes("--no-staple");
 const receiptIndex = args.indexOf("--receipt");
 const profileIndex = args.indexOf("--profile");
 const appIndex = args.indexOf("--app");
 const app = appIndex >= 0 ? args[appIndex + 1] : undefined;
 const receiptPath = receiptIndex >= 0 ? args[receiptIndex + 1] : null;
 const profile = profileIndex >= 0 ? args[profileIndex + 1] : undefined;
-const archiveArgs = args.filter((arg, index) => arg !== "--dry-run" && arg !== "--receipt" && arg !== "--profile" && arg !== "--app" && (appIndex < 0 || index !== appIndex + 1) && (receiptIndex < 0 || index !== receiptIndex + 1) && (profileIndex < 0 || index !== profileIndex + 1));
-if (archiveArgs.length !== 1) fail("usage: node notarize-macos.mjs [--dry-run] --receipt <path> [--profile <name>] [--app <bundle>] <archive>");
+const archiveArgs = args.filter((arg, index) => arg !== "--dry-run" && arg !== "--no-staple" && arg !== "--receipt" && arg !== "--profile" && arg !== "--app" && (appIndex < 0 || index !== appIndex + 1) && (receiptIndex < 0 || index !== receiptIndex + 1) && (profileIndex < 0 || index !== profileIndex + 1));
+if (archiveArgs.length !== 1) fail("usage: node notarize-macos.mjs [--dry-run] [--no-staple] --receipt <path> [--profile <name>] [--app <bundle>] <archive>");
 if (!receiptPath || receiptPath.startsWith("--")) fail("--receipt requires a path");
 if (appIndex >= 0 && (!app || app.startsWith("--"))) fail("--app requires an app bundle path");
 const archive = path.resolve(archiveArgs[0]);
@@ -23,7 +24,7 @@ if (dryRun) {
 if (process.platform !== "darwin") fail("macOS notarization must run on macOS");
 if (!existsSync(archive)) fail(`missing archive: ${archive}`);
 
-try { notarizeMacosArtifact({ archive, receiptPath, profile, app }); }
+try { notarizeMacosArtifact({ archive, receiptPath, profile, app, staple: noStaple ? false : true }); }
 catch (error) {
   if (error.report) console.error(JSON.stringify(error.report));
   fail(`${error.code ? `[${error.code}] ` : ""}${error.message}`);

package/ownership-catalog-config.json

@@ -3,16 +3,15 @@
   "newCapabilityApprovalFlag": "--approve-new-capabilities",
   "approvalScope": "Local catalog generation only; installation still requires protected authorization. This flag cannot approve owner changes.",
   "ownerFamilies": [
-    { "capability": "agent-room", "packages": ["agent-room-core", "@rightkit/agent-room-mcp"], "reason": "Native room core & MCP adapter share room contract" },
     { "capability": "licensing", "packages": ["rightkit-license", "@rightkit/license"], "reason": "Native entitlement enforcement & renderer/network client have separate roles" },
     { "capability": "structured-logging", "packages": ["rightkit-logs", "@rightkit/logs"], "reason": "Native JSONL writer & typed renderer invoke adapter" },
-    { "capability": "text-to-speech", "packages": ["rightkit-qts", "rightkit-qts-ggml", "rightkit-qts-ggml-sys", "rightkit-tts"], "reason": "Speech facade & its QTS inference, safe-wrapper & FFI layers" },
-    { "capability": "os-credential-store", "packages": ["rightkit-secrets", "RightKitSwift"], "reason": "Cross-platform Rust & Apple-native Swift credential APIs" },
-    { "capability": "desktop-shell", "packages": ["rightkit-shell", "@rightkit/shell"], "reason": "Native Tauri shell & typed renderer bridge" },
-    { "capability": "tauri-host-adapters", "packages": ["rightkit-tauri", "@rightkit/tauri"], "reason": "Native license/device services & renderer command adapters" }
+    { "capability": "text-to-speech", "packages": ["rightkit-tts-qwen", "rightkit-tts-qwen-sys", "rightkit-tts"], "reason": "Speech facade & its QTS inference, safe-wrapper & FFI layers" },
+    { "capability": "os-credential-store", "packages": ["rightkit-credentials", "RightKitSwift"], "reason": "Cross-platform Rust & Apple-native Swift credential APIs" },
+    { "capability": "desktop-shell", "packages": ["rightkit-tauri-shell", "@rightkit/tauri-shell"], "reason": "Native Tauri shell & typed renderer bridge" },
+    { "capability": "tauri-host-adapters", "packages": ["rightkit-device", "@rightkit/tauri"], "reason": "Native license/device services & renderer command adapters" }
   ],
   "testOwners": [
-    { "path": "crates/rightkit-control/examples/control-test-app/Cargo.toml", "package": "control-test-app", "reason": "Unpublished desktop-control test fixture" },
-    { "path": "crates/rightkit-shell/example-app/Cargo.toml", "package": "shell-example-app", "reason": "Unpublished standalone shell demonstration & test host" }
+    { "path": "crates/rightkit-qa-driver/examples/control-test-app/Cargo.toml", "package": "control-test-app", "reason": "Unpublished desktop-control test fixture" },
+    { "path": "crates/rightkit-tauri-shell/example-app/Cargo.toml", "package": "shell-example-app", "reason": "Unpublished standalone shell demonstration & test host" }
   ]
 }

package/ownership-command.mjs

@@ -18,6 +18,7 @@ import { spawnSync } from "./background-process.mjs";
 import { main as stagedMain } from "./ownership-staged.mjs";
 import { loadTrustedExternal } from "./ownership-approval.mjs";
 import { trustComparison } from "./ownership-policy-bundle.mjs";
+import { isBlockingFinding } from "./ownership-verdict.mjs";
 
 const packageRoot = path.dirname(fileURLToPath(import.meta.url));
 
@@ -37,7 +38,7 @@ export function trustCompare(args, { print, trustLoader = loadTrustedExternal }
   return 0;
 }
 
-export async function main(args, { evidenceFactory = createOwnershipEvidence, gitRunner = spawnSync, print = (value) => console.log(value), trustLoader = loadTrustedExternal } = {}) {
+export async function main(args, { evidenceFactory = createOwnershipEvidence, gitRunner = spawnSync, print = (value) => console.log(value), stderr = (line) => console.error(line), trustLoader = loadTrustedExternal } = {}) {
   if (args.includes("--help")) {
     print("right-release ownership [--app <dir>] [--json]\nright-release ownership --staged [--app <dir>] [--json]  (pre-commit gate: scans the index, not the working tree)\nright-release ownership --write-manifest [--rightkit <dir>] [--approve-new-capabilities]\n--approve-new-capabilities permits new capability ids during local generation only. Existing owner conflicts are always refused. Protected installation authorization remains separate.");
     return 0;
@@ -58,20 +59,27 @@ export async function main(args, { evidenceFactory = createOwnershipEvidence, gi
   }
   const app = path.resolve(flag(args, "--app") ?? process.cwd());
   const top = gitRunner("git", ["-C", app, "rev-parse", "--show-toplevel"], { encoding: "utf8", windowsHide: true });
-  if (top.status !== 0) return failClosed(args, "repository", "could not resolve --app to a Git repository");
+  if (top.status !== 0) return refuse(args, { type: "repository", message: "could not resolve --app to a Git repository" }, { print, stderr });
   const repoRoot = path.resolve(String(top.stdout).trim());
   let checked;
   try { checked = evidenceFactory(repoRoot, app); }
-  catch (error) { return failClosed(args, "protected-evidence", error.message, print); }
+  catch (error) {
+    // A refusal from the protected checkout carries its check name and offending paths.
+    const blocked = error?.blocked ? [blockedCheck(error.blocked.check, error.message, error.blocked.paths)] : undefined;
+    return refuse(args, { type: "protected-evidence", message: error.message, blocked }, { print, stderr });
+  }
   const result = checked.result;
   if (args.includes("--audit-json")) return printAuditJson(result, print);
+  // A refusal names every blocking check on stderr and in the JSON `blocked` field. Advise-tier findings never refuse.
+  const blocked = checked.enrollmentPending || checked.ok ? undefined : blockingChecks(checked);
+  if (blocked) reportBlocked(blocked, stderr);
   if (args.includes("--json")) {
     const error = checked.enrollmentPending ? undefined : !checked.floor.ok
       ? { type: "ownership-floor", message: checked.floor.problems.join("; ") }
       : result.coverage.length
         ? { type: "ownership-coverage", message: `${result.coverage.length} ownership coverage gap(s)` }
         : undefined;
-    print(JSON.stringify({ ok: checked.ok, ...(checked.enrollmentPending ? { enrollmentPending: true, warning: checked.warning } : {}), ...(error ? { error } : {}), rows: result.rows, violations: result.violations, covered: result.covered, problems: [...result.problems, ...checked.floor.problems], coverage: result.coverage, metadata: result.metadata }, null, 2));
+    print(JSON.stringify({ ok: checked.ok, ...(checked.enrollmentPending ? { enrollmentPending: true, warning: checked.warning } : {}), ...(error ? { error } : {}), ...(blocked ? { blocked } : {}), rows: result.rows, violations: result.violations, covered: result.covered, problems: [...result.problems, ...checked.floor.problems], coverage: result.coverage, metadata: result.metadata }, null, 2));
   } else {
     print(`RightKit ownership: ${path.basename(app)}`);
     print(formatTable(result.rows));
@@ -79,7 +87,7 @@ export async function main(args, { evidenceFactory = createOwnershipEvidence, gi
       print(`  OWN COPY ${v.fingerprint} (${v.package}) ${v.file}${v.line ? `:${v.line}` : ""}  ${v.text}`);
     }
     for (const p of result.problems) print(`  ${checked.enrollmentPending ? "DIAGNOSTIC" : "EXCEPTION"} ${p}`);
-    print(checked.enrollmentPending ? `[right-release] ${checked.warning}` : checked.ok ? "[right-release] ownership passed" : `[right-release] ownership FAILED: ${[...result.problems, ...checked.floor.problems].join("; ") || "move these to RightKit or add a reviewed, dated exception"}`);
+    print(verdictLine(checked, result, blocked));
   }
   // CI lanes may pass `--advisory-when-pending`: before approval keys are enrolled the scan asserts
   // nothing, so findings print as diagnostics and the step exits 0. Release lanes never pass it.
@@ -115,9 +123,62 @@ function printAuditJson(result, print) {
   }
 }
 
-function failClosed(args, type, message, print = (value) => console.log(value)) {
-  if (args.includes("--audit-json")) { console.error(`[right-release] ownership audit failed: ${message}`); return 1; }
-  if (args.includes("--json")) print(JSON.stringify({ ok: false, error: { type, message }, rows: [], violations: [], covered: [], problems: [message], coverage: [], metadata: null }, null, 2));
+// Each refusal names its blocking check and the first offending paths. Stderr and the JSON `blocked` field carry the same list.
+const BLOCKED_PATH_LIMIT = 10;
+
+function blockedCheck(check, message, paths = []) {
+  return { check, message, count: paths.length, paths: paths.slice(0, BLOCKED_PATH_LIMIT) };
+}
+
+// The checks that refuse a scan that did not pass. Advise-tier findings are never listed here.
+function blockingChecks(checked) {
+  const result = checked.result;
+  const checks = [];
+  const blocking = (result.violations ?? []).filter(isBlockingFinding);
+  if (blocking.length) checks.push(blockedCheck("ownership-violation", `${blocking.length} block-tier finding(s) duplicate RightKit owners`, blocking.map((entry) => entry.file).filter(Boolean)));
+  const floorProblems = checked.floor?.ok === false ? checked.floor.problems ?? [] : [];
+  if (floorProblems.length) checks.push(blockedCheck("ownership-floor", floorProblems.join("; ")));
+  const problems = (result.problems ?? []).filter((problem) => !floorProblems.includes(problem));
+  if (problems.length) checks.push(blockedCheck("ownership-problem", problems.join("; ")));
+  const gaps = result.coverage ?? [];
+  if (gaps.length) checks.push(blockedCheck("ownership-coverage", `${gaps.length} coverage gap(s): ${[...new Set(gaps.map((gap) => gap.reason))].join(", ")}`, gaps.map((gap) => gap.path)));
+  if (!checks.length) checks.push(blockedCheck("ownership-unknown", "scan reported not ok without a listed cause"));
+  return checks;
+}
+
+function reportBlocked(checks, stderr) {
+  for (const check of checks) {
+    stderr(`[right-release] refused by check ${check.check}: ${check.message}`);
+    for (const file of check.paths) stderr(`  - ${file}`);
+    if (check.count > check.paths.length) stderr(`  ... and ${check.count - check.paths.length} more`);
+  }
+}
+
+function tierCounts(violations) {
+  const counts = { block: 0, advise: 0 };
+  for (const violation of violations) counts[isBlockingFinding(violation) ? "block" : "advise"] += 1;
+  return counts;
+}
+
+// The human verdict line. Advise-only results pass and say so; a refusal names its checks.
+function verdictLine(checked, result, blocked) {
+  if (checked.enrollmentPending) return `[right-release] ${checked.warning}`;
+  if (checked.ok) {
+    const counts = tierCounts(result.violations ?? []);
+    return counts.advise
+      ? `[right-release] ownership ADVISE: block ${counts.block}, advise ${counts.advise} (reported, not refused)`
+      : "[right-release] ownership passed";
+  }
+  const hint = blocked.some((entry) => entry.check === "ownership-violation") ? "; move these to RightKit or add a reviewed, dated exception" : "";
+  return `[right-release] ownership FAILED: ${blocked.map((entry) => `${entry.check}: ${entry.message}`).join("; ")}${hint}`;
+}
+
+// Refusal before any verdict: unresolved repository, protected evidence, or a dirty protected checkout.
+function refuse(args, { type, message, blocked }, { print = (value) => console.log(value), stderr = (line) => console.error(line) } = {}) {
+  const checks = blocked ?? [blockedCheck(type, message)];
+  reportBlocked(checks, stderr);
+  if (args.includes("--audit-json")) { stderr(`[right-release] ownership audit failed: ${message}`); return 1; }
+  if (args.includes("--json")) print(JSON.stringify({ ok: false, error: { type, message }, blocked: checks, rows: [], violations: [], covered: [], problems: [message], coverage: [], metadata: null }, null, 2));
   else print(`[right-release] ownership FAILED: ${message}`);
   return 1;
 }

package/ownership-evidence.mjs

@@ -90,7 +90,7 @@ function createEvidence(repoRoot, {
     : { ok: false, problems: ["protected ownership floor is unavailable until trust registry enrollment"] };
   if (bundleProblem) { floor.ok = false; floor.problems = [bundleProblem, ...floor.problems.filter((problem) => !problem.startsWith("ownership policy bundle"))]; }
   // Real paths on both sides: Git's root is resolved (macOS /private/var), callers may pass /var or /tmp.
-  const real = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+  const real = (p) => { try { return realpathSync.native(p); } catch { return path.resolve(p); } };
   const requestedRoot = path.relative(real(root), real(scanRoot)).replaceAll("\\", "/") || ".";
   if (requestedRoot.startsWith("../") || requestedRoot === ".." || path.isAbsolute(requestedRoot)) throw new Error("ownership evidence scan root must be inside repository");
   const evidenceDiagnostics = [];

package/ownership-key-authority.mjs

@@ -37,7 +37,7 @@ function validateAuthority(authority) {
   if (typeof authority.checkoutPath !== "string" || !path.isAbsolute(authority.checkoutPath) || authority.checkoutPath.includes("\0")) throw new Error("protected key authority checkoutPath must be absolute");
   const repositoryIdentity = canonicalRepositoryIdentity(authority.repositoryIdentity);
   if (repositoryIdentity !== authority.repositoryIdentity) throw new Error("protected key authority identity must be canonical");
-  const checkoutPath = realpathSync(authority.checkoutPath);
+  const checkoutPath = realpathSync.native(authority.checkoutPath);
   if (!statSync(checkoutPath).isDirectory()) throw new Error("protected key authority checkoutPath must be a directory");
   return { repositoryIdentity, checkoutPath };
 }

package/ownership-key-command.mjs

@@ -41,7 +41,8 @@ function readLog(root) {
 }
 function ensureCleanMetadata(root, run, rels) {
   for (const rel of rels) assertSafeMetadataParents(root, rel);
-  const result = run("git", ["-C", root, "status", "--porcelain=v1", "--untracked-files=all"]);
+  // Limited to the metadata paths: an unscoped status of a large checkout overflows the child's output buffer.
+  const result = run("git", ["-C", root, "status", "--porcelain=v1", "--untracked-files=all", "--", ...rels]);
   if (result.status !== 0) throw new Error("could not inspect repository metadata status");
   const status = String(result.stdout ?? "");
   for (const rel of rels) {
@@ -49,7 +50,7 @@ function ensureCleanMetadata(root, run, rels) {
   }
 }
 function metadataIsDirty(root, run) {
-  const r = run("git", ["-C", root, "status", "--porcelain=v1", "--untracked-files=all"]);
+  const r = run("git", ["-C", root, "status", "--porcelain=v1", "--untracked-files=all", "--", LOG, REQUEST_DIR]);
   if (r.status !== 0) throw new Error("could not inspect repository metadata status");
   return String(r.stdout ?? "").split(/\r?\n/).some((line) => {
     const file = line.slice(3).replaceAll('"', "");
@@ -355,7 +356,7 @@ export async function main(args, deps = {}) {
   try {
     if (!platform) throw new Error(`ownership key management unsupported platform: ${process.platform}`);
     // Delegate BEFORE taking the command lock: the desktop-session child needs that same lock.
-    if (args[0] === "trust-sync" && needsDesktopDelegation({ hostPlatform: deps.hostPlatform, env: deps.env, run, elevatedCheck: deps.elevatedCheck })) return delegateTrustSync(deps, run, print);
+    if (args[0] === "trust-sync" && !args.includes("--check") && needsDesktopDelegation({ hostPlatform: deps.hostPlatform, env: deps.env, run, elevatedCheck: deps.elevatedCheck })) return delegateTrustSync(deps, run, print);
     const helper = deps.helper ?? helperFor(run);
     const lockPath = deps.lockPath ?? path.join(os.tmpdir(), "rightkit-key-command.lock");
     let lockFd;
@@ -524,6 +525,17 @@ async function trustSync(_args, d) {
   if (!trust?.trust?.rootFingerprint) throw new Error("protected root trust is not enrolled on this host; run ownership enroll");
   if (trust.trust.rootFingerprint !== pin) throw new Error("committed key log root does not match this host's protected trust");
   const baseline = d.baseline ?? parse(readFileSync(path.join(here, "ownership-default-policy.json"), "utf8"), "ownership default policy");
+  if (_args.includes("--check")) {
+    // Read-only: say whether a sync would ask for approval, and for what. Asks nothing, elevates nothing, writes no trust.
+    const request = makeTrustRequest(log, pin, baseline, d.authority);
+    try {
+      const summary = (d.summarize ?? summarizeRequestFile)({ file: request.file, digest: request.digest, existing: trust.trust, ...(d.summaryInputs ?? {}) });
+      if (!summary.changed) { d.print("trust already current: no approval needed"); return 0; }
+      d.print(summary.lines.join("\n"));
+      d.print("approval needed: trust-sync on this host would ask for the change above");
+      return 3;
+    } finally { await import("node:fs").then(({ unlinkSync }) => unlinkSync(request.file)).catch(() => {}); }
+  }
   const installed = await installCheckpoint(log, pin, baseline, d);
   if (installed === false) { d.print("trust already current"); return 0; }
   postVerify(d.root, log, d);