planning-with-files 3.11.2 → 3.14.0

package/scripts/phase-status.ps1

@@ -6,9 +6,10 @@
 .DESCRIPTION
     The ONLY sanctioned concurrent-safe writer of task_plan.md status lines. The
     orchestrator owns task_plan.md; workers NEVER edit it directly. The edit is
-    a read-modify-write under an exclusive lock on the <plan-dir>\.write_lock
-    sentinel, with an atomic temp-file + move swap so a torn write can never
-    leave a half-rewritten plan on disk (architecture C4).
+    a read-modify-write under the portable
+    <plan-dir>\.pwf-locks\phase-status.lock directory lock, with an atomic
+    temp-file + move swap so a torn write can never leave a half-rewritten plan
+    on disk (architecture C4).
 
     Editing task_plan.md changes its SHA, so the orchestrator must re-attest at
     phase boundaries (see attest-plan.ps1).
@@ -76,6 +77,70 @@ function Resolve-PlanFile {
     return $null
 }
 
+function Enter-PwfDirectoryLock {
+    param(
+        [string] $LockRoot,
+        [string] $LockDir
+    )
+
+    try {
+        [void][System.IO.Directory]::CreateDirectory($LockRoot)
+    } catch {
+        Write-Error ("[phase-status] Cannot create lock root " + $LockRoot + ": " + $_.Exception.Message)
+        return $null
+    }
+
+    $token = "phase-status-" + $PID + "-" + [Guid]::NewGuid().ToString("N")
+    $ownerFile = Join-Path $LockDir ".owner"
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+
+    $wait = [Diagnostics.Stopwatch]::StartNew()
+    while ($wait.Elapsed.TotalSeconds -lt 5) {
+        $createdByUs = $false
+        try {
+            New-Item -Path $LockDir -ItemType Directory -ErrorAction Stop | Out-Null
+            $createdByUs = $true
+            [System.IO.File]::WriteAllText($ownerFile, $token + "`n", $utf8NoBom)
+            return [PSCustomObject]@{
+                Directory = $LockDir
+                OwnerFile = $ownerFile
+                Token = $token
+            }
+        } catch {
+            if ($createdByUs) {
+                try {
+                    if ([System.IO.File]::Exists($ownerFile)) {
+                        $ownerValue = [System.IO.File]::ReadAllText($ownerFile).Trim()
+                        if ([string]::Equals($ownerValue, $token, [StringComparison]::Ordinal)) {
+                            [System.IO.File]::Delete($ownerFile)
+                        }
+                    }
+                    [System.IO.Directory]::Delete($LockDir, $false)
+                } catch {
+                    # Leave any directory we cannot prove is still ours intact.
+                }
+            }
+            Start-Sleep -Milliseconds 100
+        }
+    }
+
+    return $null
+}
+
+function Exit-PwfDirectoryLock {
+    param($Lock)
+    if (-not $Lock) { return }
+    try {
+        if (-not [System.IO.File]::Exists($Lock.OwnerFile)) { return }
+        $ownerValue = [System.IO.File]::ReadAllText($Lock.OwnerFile).Trim()
+        if (-not [string]::Equals($ownerValue, $Lock.Token, [StringComparison]::Ordinal)) { return }
+        [System.IO.File]::Delete($Lock.OwnerFile)
+        [System.IO.Directory]::Delete($Lock.Directory, $false)
+    } catch {
+        # Cleanup is best-effort and never removes a lock with another owner.
+    }
+}
+
 # Validate phase number is a positive integer.
 if ($Phase -notmatch '^[0-9]+$') {
     Write-Error ("[phase-status] phase number must be a positive integer, got '" + $Phase + "'.")
@@ -96,18 +161,16 @@ if (-not $planFile) {
 }
 
 $planDir  = Split-Path -Parent $planFile
-$lockFile = Join-Path $planDir ".write_lock"
-
-# Acquire an exclusive lock on the sentinel so concurrent writers serialize.
-$fs = $null
-$acquired = $false
-for ($i = 0; $i -lt 50 -and -not $acquired; $i++) {
-    try {
-        $fs = [System.IO.File]::Open($lockFile, [System.IO.FileMode]::OpenOrCreate, [System.IO.FileAccess]::ReadWrite, [System.IO.FileShare]::None)
-        $acquired = $true
-    } catch {
-        Start-Sleep -Milliseconds 100
-    }
+$lockRoot = Join-Path $planDir ".pwf-locks"
+$lockDir  = Join-Path $lockRoot "phase-status.lock"
+
+# Atomic directory creation is the common lock primitive used by both the sh
+# and PowerShell implementations. Failure to acquire within about five seconds
+# is fail-closed: no plan read/rewrite is attempted.
+$lock = Enter-PwfDirectoryLock -LockRoot $lockRoot -LockDir $lockDir
+if (-not $lock) {
+    Write-Error ("[phase-status] Timed out waiting for lock " + $lockDir + ". No plan changes were made.")
+    exit 75
 }
 
 $tmpFile = $planFile + ".tmp." + $PID
@@ -164,8 +227,7 @@ try {
     Write-Error ("[phase-status] " + $_.Exception.Message)
     $rc = 1
 } finally {
-    if ($fs) { $fs.Close(); $fs.Dispose() }
-    if (Test-Path -LiteralPath $lockFile) { Remove-Item -LiteralPath $lockFile -Force -ErrorAction SilentlyContinue }
+    Exit-PwfDirectoryLock -Lock $lock
     if (Test-Path -LiteralPath $tmpFile) { Remove-Item -LiteralPath $tmpFile -Force -ErrorAction SilentlyContinue }
 }
 

package/scripts/phase-status.sh

@@ -3,9 +3,10 @@
 #
 # This is the ONLY sanctioned concurrent-safe writer of task_plan.md status
 # lines. The orchestrator owns task_plan.md; workers NEVER edit it directly.
-# All status edits go through this read-modify-write under an advisory flock on
-# the <plan-dir>/.write_lock sentinel, with an atomic temp-file + mv swap so a
-# torn write can never leave a half-rewritten plan on disk (architecture C4).
+# All status edits go through this read-modify-write under the portable
+# <plan-dir>/.pwf-locks/phase-status.lock directory lock, with an atomic
+# temp-file + mv swap so a torn write can never leave a half-rewritten plan on
+# disk (architecture C4).
 #
 # Note: editing task_plan.md changes its SHA, so the orchestrator must
 # re-attest at phase boundaries (see attest-plan.sh).
@@ -77,9 +78,62 @@ PLAN_FILE="$(resolve_plan_file)" || {
 }
 
 PLAN_DIR="$(dirname "${PLAN_FILE}")"
-LOCK_FILE="${PLAN_DIR}/.write_lock"
+LOCK_ROOT="${PLAN_DIR}/.pwf-locks"
+LOCK_DIR="${LOCK_ROOT}/phase-status.lock"
+LOCK_TOKEN=""
+LOCK_ACQUIRED=0
 
-# Confirm the phase heading exists before touching the file.
+release_lock() {
+    if [ "${LOCK_ACQUIRED}" -ne 1 ] || [ -z "${LOCK_TOKEN}" ]; then
+        return 0
+    fi
+    owner_file="${LOCK_DIR}/.owner"
+    owner_value="$(cat "${owner_file}" 2>/dev/null || true)"
+    if [ "${owner_value}" = "${LOCK_TOKEN}" ]; then
+        rm -f "${owner_file}" 2>/dev/null || true
+        rmdir "${LOCK_DIR}" 2>/dev/null || true
+    fi
+    LOCK_ACQUIRED=0
+}
+
+acquire_lock() {
+    mkdir -p "${LOCK_ROOT}" 2>/dev/null || {
+        printf "[phase-status] Cannot create lock root %s.\n" "${LOCK_ROOT}" >&2
+        return 1
+    }
+    LOCK_TOKEN="phase-status-$$-$(date +%s 2>/dev/null || printf 0)"
+    started_at="$(date +%s 2>/dev/null || printf 0)"
+    attempts=0
+    while ! mkdir "${LOCK_DIR}" 2>/dev/null; do
+        attempts=$((attempts + 1))
+        now="$(date +%s 2>/dev/null || printf 0)"
+        if { [ "${started_at}" -gt 0 ] 2>/dev/null \
+                && [ $((now - started_at)) -ge 5 ]; } \
+            || [ "${attempts}" -ge 50 ]; then
+            printf "[phase-status] Timed out waiting for lock %s. No plan changes were made.\n" "${LOCK_DIR}" >&2
+            return 75
+        fi
+        sleep 0.1
+    done
+    if ! printf '%s\n' "${LOCK_TOKEN}" > "${LOCK_DIR}/.owner" 2>/dev/null; then
+        rmdir "${LOCK_DIR}" 2>/dev/null || true
+        printf "[phase-status] Cannot record lock ownership in %s.\n" "${LOCK_DIR}" >&2
+        return 1
+    fi
+    LOCK_ACQUIRED=1
+    return 0
+}
+
+trap 'release_lock' EXIT
+trap 'release_lock; exit 1' HUP INT TERM
+
+acquire_lock
+lock_rc=$?
+if [ "${lock_rc}" -ne 0 ]; then
+    exit "${lock_rc}"
+fi
+
+# Confirm the phase heading exists while holding the same lock as the rewrite.
 if ! grep -q "### Phase ${PHASE_NUM}\b" "${PLAN_FILE}" 2>/dev/null; then
     # Fall back to a looser match for headings like "### Phase 1:" where \b may
     # not be honored by a minimal grep.
@@ -137,17 +191,7 @@ do_write() {
 }
 
 rc=0
-if command -v flock >/dev/null 2>&1; then
-    (
-        flock -w 5 9 || true
-        do_write
-    ) 9>"${LOCK_FILE}" 2>/dev/null
-    rc=$?
-    rm -f "${LOCK_FILE}" 2>/dev/null || true
-else
-    do_write
-    rc=$?
-fi
+do_write || rc=$?
 
 if [ "${rc}" -ne 0 ]; then
     rm -f "${TMP_FILE}" 2>/dev/null

package/scripts/resolve-plan-dir.ps1

@@ -18,6 +18,64 @@ param(
 
 $projectRoot = (Get-Location).Path
 
+# Resolve-Path is lexical for Windows junctions: it can return the junction's
+# spelling rather than the directory opened by the filesystem. Use a directory
+# handle and GetFinalPathNameByHandleW on Windows so containment is decided from
+# the object the kernel actually opened.
+$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
+if ($script:IsWindowsHost -and -not ("PwfResolverNative" -as [type])) {
+    Add-Type -TypeDefinition @'
+using System;
+using System.ComponentModel;
+using System.Runtime.InteropServices;
+using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+public static class PwfResolverNative {
+    private const uint FILE_SHARE_READ = 0x00000001;
+    private const uint FILE_SHARE_WRITE = 0x00000002;
+    private const uint FILE_SHARE_DELETE = 0x00000004;
+    private const uint OPEN_EXISTING = 3;
+    private const uint FILE_FLAG_BACKUP_SEMANTICS = 0x02000000;
+
+    [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);
+
+    public static string FinalDirectoryPath(string path) {
+        using (SafeFileHandle handle = CreateFileW(
+            path, 0, FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
+            IntPtr.Zero, OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS, 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;
+        }
+    }
+}
+'@
+}
+
+function Get-FinalDirectoryPath {
+    param([string]$Path)
+    if ($script:IsWindowsHost) {
+        return [PwfResolverNative]::FinalDirectoryPath($Path)
+    }
+    return (Resolve-Path -LiteralPath $Path -ErrorAction Stop).Path
+}
+
 # PWF_PLAN_ROOT: absolute plan-root binding (issue #212), mirroring
 # resolve-plan-dir.sh. A thread whose cwd is a shared PARENT of the real
 # project resolves the parent's plan and never sees the nested one;
@@ -30,9 +88,12 @@ $projectRoot = (Get-Location).Path
 # user-facing notice; stdout here is the data channel). Containment is then
 # checked against the pinned root. Unset keeps legacy behavior unchanged.
 if ($env:PWF_PLAN_ROOT) {
-    if (Test-Path -LiteralPath $env:PWF_PLAN_ROOT -PathType Container) {
-        $projectRoot = $env:PWF_PLAN_ROOT
-        $PlanRoot = Join-Path $env:PWF_PLAN_ROOT ".planning"
+    $pin = $env:PWF_PLAN_ROOT
+    $isUnc = $pin.StartsWith('\\') -or $pin.StartsWith('//')
+    $isAbsolute = [System.IO.Path]::IsPathFullyQualified($pin)
+    if ($isAbsolute -and -not $isUnc -and (Test-Path -LiteralPath $pin -PathType Container)) {
+        $projectRoot = $pin
+        $PlanRoot = Join-Path $pin ".planning"
     } else {
         exit 0
     }
@@ -55,8 +116,8 @@ function Test-ValidSlug {
 function Test-WithinRoot {
     param([string]$Candidate)
     try {
-        $rootReal = (Resolve-Path -LiteralPath $projectRoot -ErrorAction Stop).Path
-        $candReal = (Resolve-Path -LiteralPath $Candidate -ErrorAction Stop).Path
+        $rootReal = Get-FinalDirectoryPath $projectRoot
+        $candReal = Get-FinalDirectoryPath $Candidate
     } catch {
         return $false
     }
@@ -79,8 +140,17 @@ if ($env:PLAN_ID) {
     }
 }
 
-if (Test-Path $activeFile) {
-    $planId = (Get-Content $activeFile -Raw).Trim()
+# Get-Item observes the link object even when its target is missing, unlike
+# Test-Path which follows the target. An active pointer that is a directory or
+# reparse point is an unsafe/ambiguous selector and must terminate resolution;
+# falling through would silently select and expose the newest unrelated plan.
+$activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
+if ($activeItem) {
+    if ($activeItem.PSIsContainer -or
+        (($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
+        exit 0
+    }
+    $planId = (Get-Content -LiteralPath $activeFile -Raw).Trim()
     if ($planId -and (Test-ValidSlug $planId)) {
         $candidate = Join-Path $PlanRoot $planId
         if ((Test-Path $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {

package/scripts/resolve-plan-dir.sh

@@ -31,7 +31,12 @@ PLAN_ROOT="${1:-${PWD}/.planning}"
 # With the variable unset, behavior is byte-identical to the legacy shape.
 PWF_ROOT_PIN=""
 if [ -n "${PWF_PLAN_ROOT:-}" ]; then
-    if [ -d "${PWF_PLAN_ROOT}" ]; then
+    case "${PWF_PLAN_ROOT}" in
+        \\\\*|//*|[A-Za-z]:[!\\/]*) _pwf_pin_absolute=0 ;;
+        /*|[A-Za-z]:[\\/]*) _pwf_pin_absolute=1 ;;
+        *) _pwf_pin_absolute=0 ;;
+    esac
+    if [ "$_pwf_pin_absolute" = "1" ] && [ -d "${PWF_PLAN_ROOT}" ]; then
         PWF_ROOT_PIN="${PWF_PLAN_ROOT}"
         PLAN_ROOT="${PWF_PLAN_ROOT}/.planning"
     else
@@ -85,10 +90,54 @@ norm_slashes() {
     done
 }
 
+# Return true when a candidate path names the Microsoft Store WindowsApps
+# directory. Store app aliases are not stable interpreter binaries and may
+# present as executable while refusing script execution. Matching is
+# case-insensitive and works before or after Windows slash normalization.
+is_windowsapps_path() {
+    norm_slashes "$1"
+    case "${NORM_OUT}" in
+        [Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
+        [Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
+        */[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
+        */[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
+    esac
+    return 1
+}
+
+# Select only an interpreter path the caller explicitly trusted.
+# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
+# PATH discovery is intentionally forbidden because resolver hooks can run in
+# repositories that control PATH. Windows-native absolute paths are converted
+# with Git Bash's fixed system cygpath, never a PATH-selected shim.
+trusted_python() {
+    for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
+        [ -n "${_tp_candidate}" ] || continue
+        case "${_tp_candidate}" in
+            \\\\*|//*) continue ;;
+            [A-Za-z]:[\\/]*)
+                is_windowsapps_path "${_tp_candidate}" && continue
+                _tp_cygpath="/usr/bin/cygpath.exe"
+                [ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
+                _tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
+                    || continue
+                ;;
+            /*) ;;
+            *) continue ;;
+        esac
+        is_windowsapps_path "${_tp_candidate}" && continue
+        [ -f "${_tp_candidate}" ] || continue
+        [ -x "${_tp_candidate}" ] || continue
+        printf "%s\n" "${_tp_candidate}"
+        return 0
+    done
+    return 1
+}
+
 # Portable path canonicalizer. realpath first (Linux, modern coreutils),
-# then readlink -f (older GNU), then python3/python os.path.realpath. Prints
-# the canonical absolute path on success; prints nothing and returns 1 on a
-# full miss so the caller can decide what to do. No python spawn on the happy
+# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
+# Prints the canonical absolute path on success; prints nothing and returns 1
+# on a full miss so containment fails closed. No Python spawn on the happy
 # path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
 canonicalize() {
     target="$1"
@@ -100,12 +149,9 @@ canonicalize() {
         out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
             printf "%s\n" "${out}"; return 0; }
     fi
-    if command -v python3 >/dev/null 2>&1; then
-        out="$(python3 -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
-            && [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
-    fi
-    if command -v python >/dev/null 2>&1; then
-        out="$(python -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
+    _canonical_python="$(trusted_python)" || _canonical_python=""
+    if [ -n "${_canonical_python}" ]; then
+        out="$("${_canonical_python}" -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
             && [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
     fi
     return 1
@@ -175,7 +221,8 @@ is_within_root() {
 }
 
 # Portable mtime resolver. Tries GNU stat, BSD stat, BSD/macOS date -r,
-# python3, then perl. Returns "0" on full miss so callers can sort.
+# then an explicitly trusted Python interpreter. Returns "0" on a full miss
+# so newest-plan selection fails closed instead of executing from PATH.
 mtime_of() {
     target="$1"
     out="$(stat -c '%Y' "${target}" 2>/dev/null)"
@@ -184,16 +231,9 @@ mtime_of() {
     if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
     out="$(date -r "${target}" +%s 2>/dev/null)"
     if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
-    if command -v python3 >/dev/null 2>&1; then
-        out="$(python3 -c "import os,sys;print(int(os.stat(sys.argv[1]).st_mtime))" "${target}" 2>/dev/null)"
-        if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
-    fi
-    if command -v python >/dev/null 2>&1; then
-        out="$(python -c "import os,sys;print(int(os.stat(sys.argv[1]).st_mtime))" "${target}" 2>/dev/null)"
-        if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
-    fi
-    if command -v perl >/dev/null 2>&1; then
-        out="$(perl -e 'print((stat shift)[9])' "${target}" 2>/dev/null)"
+    _mtime_python="$(trusted_python)" || _mtime_python=""
+    if [ -n "${_mtime_python}" ]; then
+        out="$("${_mtime_python}" -c "import os,sys;print(int(os.stat(sys.argv[1]).st_mtime))" "${target}" 2>/dev/null)"
         if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
     fi
     printf "0\n"