Files
OthmanAdi 4c2b269d30 fix(powershell): keep a successful pointer switch successful
The cleanup after replacement returned failure on the first failed
inspection. With concurrent selectors the pointer is briefly missing
while another writer replaces it, so a call whose own Replace had
already succeeded exited 1 and left its .replace-backup behind: about 1
in 10 calls in an 8-writer stress run on Windows PowerShell 5.1 and
pwsh 7. Because the pointer was already switched, init-session.ps1 then
skipped the gated-mode files for a plan that was active.

Retry transient inspection failures instead of giving up. After a
successful Replace, only delete the owned backup: it holds the
superseded value, so it is never moved back and never gated on the
current pointer, and failing to delete it is a warning, not an error.
The regression test holds the backup open after a successful Replace
and expects exit 0, the new pointer and the warning.
2026-09-25 16:40:55 +02:00

422 lines
18 KiB
PowerShell
Executable File

# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
if ($PSVersionTable.PSVersion.Major -eq 5 -and
[System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
$processArgs = [Environment]::GetCommandLineArgs()
for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
if ($processArgs[$index] -ieq '-File') {
$entryScript = $processArgs[$index + 1]
if (-not [IO.Path]::IsPathRooted($entryScript)) {
$entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
}
if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
function Test-SafeActiveFile {
param([switch]$AllowLink)
$item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
# Reading may follow a verified in-project link; writing must not. A link
# is a symlink or junction by LinkType, never the bare ReparsePoint
# attribute: OneDrive Files On-Demand marks every synced file as a
# reparse point, and the pointer must stay writable there (#275).
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and
($AllowLink -or -not $linked) -and
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
function Test-SafeOwnedBackupFile {
param([string]$Path)
$item = Get-Item -LiteralPath $Path -Force -ErrorAction SilentlyContinue
if (-not $item) { return $false }
$linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
return -not $item.PSIsContainer -and -not $linked -and (Test-WithinRoot $Path)
}
function Resolve-OwnedPointerBackup {
param([string]$BackupFile, [switch]$ReplaceSucceeded)
# ReplaceFile can move the old destination before failing to move the new
# file. A caller-named backup makes that intermediate state attributable to
# this invocation, so recover or delete only this GUID path. Never glob for
# ~RF*.TMP: a concurrent selector may own those files.
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
$backupItem = Get-Item -LiteralPath $BackupFile -Force -ErrorAction SilentlyContinue
if (-not $backupItem) { return $true }
# A failed inspection is transient under concurrent writers: retry.
if (-not (Test-SafeOwnedBackupFile $BackupFile)) { Start-Sleep -Milliseconds 25; continue }
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
# After our own successful replacement the backup holds a superseded
# value: only delete it, never move it back over a newer pointer.
if ($ReplaceSucceeded -or $currentActive) {
if (-not $ReplaceSucceeded -and -not (Test-SafeActiveFile)) { Start-Sleep -Milliseconds 25; continue }
try {
[IO.File]::Delete($BackupFile)
return $true
} catch {
if ($attempt -eq $maxAttempts) { return $false }
}
} else {
try {
[IO.File]::Move($BackupFile, $ActiveFile)
return $true
} catch {
# Another selector may have recreated the pointer between the
# absence check and Move. Reinspect before deciding whether the
# owned backup is now redundant.
if ($attempt -eq $maxAttempts) { return $false }
}
}
Start-Sleep -Milliseconds 25
}
return $false
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} else {
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
}
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file and caller-owned backup live beside the pointer, keeping replacement on
# the same filesystem. Naming the backup prevents ReplaceFile from inventing
# an unowned ~RF*.TMP path if its final rename fails.
$operationId = [guid]::NewGuid().ToString('N')
$tempFile = Join-Path $PlanRoot ('.active_plan.' + $operationId + '.tmp')
$backupFile = Join-Path $PlanRoot ('.active_plan.' + $operationId + '.replace-backup')
$createdTemp = $false
$failureMessage = ""
$backupResolved = $true
$replaced = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$stream.Write($bytes, 0, $bytes.Length)
$stream.Flush()
} finally { $stream.Dispose() }
$maxAttempts = 20
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
try {
$currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($currentActive) {
if (-not (Test-SafeActiveFile)) {
throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
}
[IO.File]::Replace($tempFile, $ActiveFile, $backupFile)
} else {
[IO.File]::Move($tempFile, $ActiveFile)
}
$replaced = $true
break
} catch [IO.IOException] {
if (-not (Resolve-OwnedPointerBackup -BackupFile $backupFile)) {
throw [IO.IOException]::new("could not safely recover the active plan pointer after replacement failure")
}
if ($attempt -eq $maxAttempts) { throw }
Start-Sleep -Milliseconds 25
}
}
} catch {
$failureMessage = $_.Exception.Message
} finally {
if (-not (Resolve-OwnedPointerBackup -BackupFile $backupFile -ReplaceSucceeded:$replaced)) {
# The pointer was written; a leftover backup is clutter, not failure.
if ($replaced) { Write-Warning "could not remove the replacement backup $backupFile" }
else { $backupResolved = $false }
}
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
if (-not $backupResolved) {
Write-Error "Error: could not safely recover the active plan pointer backup."
exit 1
}
if ($failureMessage) {
Write-Error "Error: could not set the active plan pointer: $failureMessage"
exit 1
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
Write-Output "To pin this terminal session only:"
Write-Output "`$env:PLAN_ID = '$PlanId'"