planning-with-files 3.9.0

package/scripts/plan-doctor.sh

@@ -0,0 +1,148 @@
+#!/bin/sh
+# planning-with-files: plan-doctor — one-pass self-check for the mechanisms
+# that fail silently. Run from the project root:
+#
+#   sh scripts/plan-doctor.sh
+#
+# Answers:
+#   - does plan resolution work here, and which plan wins?
+#   - does hook injection actually emit plan context?
+#   - is the canonicalizer producing comparable paths? (Windows-native
+#     coreutils emit C:\-style output; pwf versions before v3.6.0 went
+#     silently dark on such machines)
+#   - is the plan attested, and is the attestation file where hooks look?
+#   - which install surfaces exist on this machine?
+#   - what does one hook fire cost in wall-clock?
+#
+# Diagnostic only. Writes nothing except inject-plan.sh's own SHA cache.
+# Always exits 0.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd 2>/dev/null)" || SCRIPT_DIR="."
+
+ok()   { printf 'PASS  %s\n' "$1"; }
+warn() { printf 'WARN  %s\n' "$1"; }
+fail() { printf 'FAIL  %s\n' "$1"; }
+info() { printf 'info  %s\n' "$1"; }
+
+echo '=== planning-with-files plan-doctor ==='
+info "cwd: ${PWD}"
+info "uname: $(uname -s 2>/dev/null || echo unknown)"
+[ "${PLANNING_DISABLED:-}" = "1" ] && warn "PLANNING_DISABLED=1 is set — every hook exits immediately in this environment"
+
+# --- [1] canonicalizer probe -------------------------------------------------
+CANON="$(realpath . 2>/dev/null)" || CANON=""
+[ -z "${CANON}" ] && { CANON="$(readlink -f . 2>/dev/null)" || CANON=""; }
+case "${CANON}" in
+    '')
+        warn "no realpath/readlink canonicalizer answered — containment falls back to a python spawn per check"
+        ;;
+    *\\*)
+        info "canonicalizer emits Windows-style paths (${CANON}) — handled since v3.6.0; OLDER pwf versions resolve nothing on this machine"
+        ;;
+    *)
+        info "canonicalizer: ${CANON}"
+        ;;
+esac
+
+# --- [2] plan resolution -----------------------------------------------------
+RES=""
+if [ -f "${SCRIPT_DIR}/resolve-plan-dir.sh" ]; then
+    RES="$(sh "${SCRIPT_DIR}/resolve-plan-dir.sh" 2>/dev/null)" || RES=""
+    if [ -n "${RES}" ]; then
+        ok "resolver: active plan dir = ${RES}"
+    elif [ -f task_plan.md ]; then
+        ok "resolver: legacy root plan (./task_plan.md)"
+    elif [ -d .planning ]; then
+        fail "resolver: .planning/ exists but nothing resolves — check .planning/.active_plan content and that plan dirs contain task_plan.md"
+    else
+        info "resolver: no plan in this directory (run init-session.sh to create one)"
+    fi
+else
+    warn "resolve-plan-dir.sh not found next to plan-doctor — unexpected install layout"
+fi
+
+# --- [3] hook injection ------------------------------------------------------
+INJ="${SCRIPT_DIR}/inject-plan.sh"
+if [ -f "${INJ}" ]; then
+    OUT="$(sh "${INJ}" --context=userprompt 2>/dev/null)" || OUT=""
+    if [ -z "${OUT}" ]; then
+        if [ -n "${RES}" ] || [ -f task_plan.md ]; then
+            fail "injection: a plan resolves but inject-plan.sh emitted NOTHING — hooks are dark. Known silent causes: pre-v3.6.0 with a Windows-native realpath on PATH; PLANNING_DISABLED=1; a plan dir outside the project root; a stale .planning/sessions/ dir with no attached session (silences pretool/precompact fires entirely — the userprompt fire names it)."
+        else
+            ok "injection: silent because no plan exists here (correct behavior)"
+        fi
+    else
+        case "${OUT}" in
+            *'PLAN TAMPERED'*)
+                warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
+                ;;
+            *'requires attested plan'*)
+                warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
+                ;;
+            *'Session isolation is armed'*)
+                # Refusal notice, not plan context: reporting its byte count as
+                # PASS told a dark user their hooks were fine.
+                warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
+                ;;
+            *'Ambiguous plan'*)
+                warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
+                ;;
+            *'PWF_PLAN_ROOT is not a directory'*)
+                warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
+                ;;
+            *)
+                BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
+                ok "injection: emits plan context (${BYTES} bytes)"
+                ;;
+        esac
+    fi
+else
+    warn "inject-plan.sh not found next to plan-doctor — this install route ships no hook payload (see the install matrix in docs/installation.md)"
+fi
+
+# --- [4] attestation ---------------------------------------------------------
+ATT=""
+if [ -n "${RES}" ] && [ -f "${RES}/.attestation" ]; then
+    ATT="${RES}/.attestation"
+elif [ -f .plan-attestation ]; then
+    ATT=".plan-attestation"
+fi
+if [ -n "${ATT}" ]; then
+    info "attestation present: ${ATT}"
+else
+    info "attestation: none (opt-in in legacy mode; default-on in v3 modes; run /plan-attest after approving the plan)"
+fi
+
+# --- [5] install surfaces ----------------------------------------------------
+FOUND_SURFACE=0
+for s in \
+    ".claude/skills/planning-with-files" \
+    "${HOME:-}/.claude/skills/planning-with-files" \
+    ".agents/skills/planning-with-files" \
+    "${HOME:-}/.agents/skills/planning-with-files"
+do
+    [ -n "${s}" ] && [ -d "${s}" ] && { info "install surface present: ${s}"; FOUND_SURFACE=1; }
+done
+[ "${FOUND_SURFACE}" = "0" ] && info "no skill-dir install surface in project or home (plugin-route installs live under the plugin cache instead)"
+info "route reminder: the plugin route ships commands/ + hooks; npx-skills ships the skill only. Hooks silent after a project-level skill install? Check project trust (hasTrustDialogAccepted) and the install matrix in docs/installation.md."
+
+# --- [6] hook latency --------------------------------------------------------
+if [ -f "${INJ}" ]; then
+    T0="$(date +%s%N 2>/dev/null)" || T0=""
+    sh "${INJ}" --context=userprompt >/dev/null 2>&1
+    T1="$(date +%s%N 2>/dev/null)" || T1=""
+    case "${T0}${T1}" in
+        ''|*[!0-9]*)
+            info "hook latency: skipped (no nanosecond clock on this date binary)"
+            ;;
+        *)
+            MS=$(( (T1 - T0) / 1000000 ))
+            info "one inject-plan.sh fire: ${MS}ms wall-clock"
+            ;;
+    esac
+fi
+
+echo '=== plan-doctor done ==='
+exit 0

package/scripts/resolve-plan-dir.ps1

@@ -0,0 +1,106 @@
+# planning-with-files: resolve active plan directory (PowerShell mirror).
+#
+# Resolution order matches scripts/resolve-plan-dir.sh:
+#   1. $env:PLAN_ID -> .\.planning\$PLAN_ID\
+#   2. .\.planning\.active_plan content
+#   3. Newest .\.planning\<dir>\ by LastWriteTime
+#   4. Empty (legacy fallback to .\task_plan.md handled by caller)
+#
+# v3.8.0 parity with the sh resolver: slug validation on every branch, the
+# newest-dir scan requires task_plan.md inside the candidate (a sessions/ or
+# artifacts/ dir must never win), and containment fails CLOSED when
+# canonicalization fails. Only successful canonicalization can rule out a
+# junction/symlink escape; slug validation alone blocks textual traversal.
+
+param(
+    [string]$PlanRoot = (Join-Path (Get-Location) ".planning")
+)
+
+$projectRoot = (Get-Location).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;
+# PWF_PLAN_ROOT names the project root whose .planning must be used. Highest
+# precedence: it overrides both the cwd default and the -PlanRoot argument
+# (an adapter passing ".planning" is spelling out the cwd default, not
+# overriding a user's deliberate pin). A pin that is not a directory fails
+# CLOSED: the resolver emits nothing, so no caller can be handed the
+# ambiguous cwd plan the pin was escaping (injection routes own the
+# 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"
+    } else {
+        exit 0
+    }
+}
+
+# Same shape as the sh resolver's slug_is_valid: first char [A-Za-z0-9_],
+# rest [A-Za-z0-9._-]. Blocks traversal tokens before any path is built.
+function Test-ValidSlug {
+    param([string]$Name)
+    if (-not $Name) { return $false }
+    return $Name -match '^[A-Za-z0-9_][A-Za-z0-9._-]*$'
+}
+
+# Containment guard (security A1.3): a resolved plan dir must canonicalize to
+# a path under the project root. A directory symlink/junction inside a valid
+# slug pointing outside the workspace would otherwise let the hooks hash and
+# inject an arbitrary file. Resolve-Path follows reparse points; we compare
+# the real paths. Fails CLOSED on canonicalization failure, matching
+# resolve-plan-dir.sh.
+function Test-WithinRoot {
+    param([string]$Candidate)
+    try {
+        $rootReal = (Resolve-Path -LiteralPath $projectRoot -ErrorAction Stop).Path
+        $candReal = (Resolve-Path -LiteralPath $Candidate -ErrorAction Stop).Path
+    } catch {
+        return $false
+    }
+    if (-not $rootReal -or -not $candReal) { return $false }
+    $rootNorm = $rootReal.TrimEnd('\', '/')
+    $candNorm = $candReal.TrimEnd('\', '/')
+    if ($candNorm -eq $rootNorm) { return $true }
+    return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
+}
+
+$activeFile = Join-Path $PlanRoot ".active_plan"
+
+if ($env:PLAN_ID) {
+    if (Test-ValidSlug $env:PLAN_ID) {
+        $candidate = Join-Path $PlanRoot $env:PLAN_ID
+        if ((Test-Path $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
+            Write-Output $candidate
+            exit 0
+        }
+    }
+}
+
+if (Test-Path $activeFile) {
+    $planId = (Get-Content $activeFile -Raw).Trim()
+    if ($planId -and (Test-ValidSlug $planId)) {
+        $candidate = Join-Path $PlanRoot $planId
+        if ((Test-Path $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
+            Write-Output $candidate
+            exit 0
+        }
+    }
+}
+
+if (Test-Path $PlanRoot -PathType Container) {
+    $latest = Get-ChildItem -Path $PlanRoot -Directory |
+        Where-Object { -not $_.Name.StartsWith('.') } |
+        Where-Object { Test-ValidSlug $_.Name } |
+        Where-Object { Test-Path (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
+        Where-Object { Test-WithinRoot $_.FullName } |
+        Sort-Object LastWriteTime -Descending |
+        Select-Object -First 1
+    if ($latest) {
+        Write-Output $latest.FullName
+    }
+}
+
+exit 0

package/scripts/resolve-plan-dir.sh

@@ -0,0 +1,263 @@
+#!/bin/sh
+# planning-with-files: resolve active plan directory.
+#
+# Resolution order:
+#   1. $PLAN_ID env var → ./.planning/$PLAN_ID/ if exists
+#   2. ./.planning/.active_plan content → matching dir if exists
+#   3. Newest ./.planning/<dir>/ by mtime
+#   4. Otherwise empty stdout (caller falls back to legacy ./task_plan.md)
+#
+# Always exits 0. Never errors out the agent loop.
+#
+# Usage:
+#   PLAN_DIR="$(sh scripts/resolve-plan-dir.sh)"
+#   PLAN_FILE="${PLAN_DIR:+$PLAN_DIR/}task_plan.md"
+
+set -u
+
+PLAN_ROOT="${1:-${PWD}/.planning}"
+
+# --- PWF_PLAN_ROOT: absolute plan-root binding (issue #212). ---
+# A thread whose cwd is a shared PARENT of the real project (e.g. /workspace
+# holding /workspace/project with its own .planning) resolves the parent's
+# plan on every call and never sees the nested one. PWF_PLAN_ROOT names the
+# project root whose .planning must be used. It is the highest-precedence
+# binding: it overrides both the ${PWD} default and the positional argument,
+# because an adapter passing ".planning" is spelling out the cwd default, not
+# overriding a user's deliberate pin. A pin that is not a directory fails
+# CLOSED: the resolver emits nothing, so no caller can be handed the
+# ambiguous cwd plan the pin was escaping (the injection routes own the
+# user-facing notice; stdout here is the data channel and must stay clean).
+# 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
+        PWF_ROOT_PIN="${PWF_PLAN_ROOT}"
+        PLAN_ROOT="${PWF_PLAN_ROOT}/.planning"
+    else
+        exit 0
+    fi
+fi
+
+ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
+
+# Plan-id safe-identifier check. Rejects whitespace, path separators, leading
+# dots, and empty strings; accepts the YYYY-MM-DD-<slug> shape from
+# init-session.sh as well as legacy hand-created names like "alpha" or
+# "feature-foo". The intent is to filter garbage content (e.g. a corrupt
+# .active_plan file containing only whitespace or random text) without
+# enforcing a date prefix that would break backward compatibility.
+# Pure-sh case patterns; semantics match the previous
+# grep -E '^[A-Za-z0-9_][A-Za-z0-9._-]*$' exactly, without a grep fork per
+# candidate (the newest-mtime scan calls this once per plan dir).
+slug_is_valid() {
+    case "$1" in
+        '') return 1 ;;
+        *[!A-Za-z0-9._-]*) return 1 ;;
+        [A-Za-z0-9_]*) return 0 ;;
+    esac
+    return 1
+}
+
+# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
+# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
+# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
+# backslash output. The containment prefix match below is written with forward
+# slashes, so without this normalization every canonical pair mismatches and
+# resolution silently fails. On POSIX systems paths contain no backslash and
+# this is the identity. A literal backslash in a Unix filename normalizes to
+# "/" and at worst fails containment — the safe direction. No subshell, no
+# fork: plain parameter expansion in a loop.
+norm_slashes() {
+    NORM_OUT=""
+    _ns_rest="$1"
+    while :; do
+        case "${_ns_rest}" in
+            *\\*)
+                NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
+                _ns_rest="${_ns_rest#*\\}"
+                ;;
+            *)
+                NORM_OUT="${NORM_OUT}${_ns_rest}"
+                break
+                ;;
+        esac
+    done
+}
+
+# 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
+# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
+canonicalize() {
+    target="$1"
+    if command -v realpath >/dev/null 2>&1; then
+        out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
+            printf "%s\n" "${out}"; return 0; }
+    fi
+    if command -v readlink >/dev/null 2>&1; then
+        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)" \
+            && [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
+    fi
+    return 1
+}
+
+# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
+# path under the project root (the CWD the script runs from). A symlink inside
+# a valid slug dir pointing at /etc or outside the workspace would otherwise let
+# the hooks hash and inject an arbitrary file. On any violation we return 1 so
+# the caller treats the candidate as unresolved and falls back safely.
+#
+# The root canonicalizes via the relative token "." rather than the $PWD
+# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
+# realpath("$PWD") and realpath(relative-candidate) resolve through different
+# code paths and land on differently-spelled-but-equal targets, so the prefix
+# match below fails and resolution silently goes dark. "." resolves through
+# the same physical-cwd path candidates already use (same fix inject-plan.sh
+# received earlier; the resolver kept the $PWD form until now). Both sides are
+# backslash-normalized before comparison for Windows-native canonicalizers.
+# The root is computed once per run: the newest-mtime scan calls this guard
+# per plan dir, and each canonicalize costs a process spawn on Windows.
+#
+# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
+# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
+# both sides canonicalize through the same path spelling. Unpinned keeps the
+# relative "." root — byte-identical to the legacy check.
+ROOT_REAL=""
+ROOT_REAL_SET=0
+is_within_root() {
+    candidate="$1"
+    if [ "${ROOT_REAL_SET}" = "0" ]; then
+        ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
+        norm_slashes "${ROOT_REAL}"
+        ROOT_REAL="${NORM_OUT}"
+        ROOT_REAL_SET=1
+    fi
+    # Canonicalize the candidate through its cwd-RELATIVE form whenever it
+    # lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
+    # long-form spelling), while the root canonicalizes from "." (the process
+    # cwd, which a caller may have set with an 8.3 short-form string). A
+    # Windows-native realpath does not unify those spellings, so canonicalizing
+    # both sides from the same cwd base is the only spelling-stable comparison.
+    # The emitted result keeps the original absolute candidate — only the
+    # containment check uses the relative form.
+    # Pinned resolution skips the rewrite: candidate and root then share the
+    # ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
+    if [ -n "${PWF_ROOT_PIN}" ]; then
+        check_target="${candidate}"
+    else
+        case "${candidate}" in
+            "${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
+            *) check_target="${candidate}" ;;
+        esac
+    fi
+    cand_real="$(canonicalize "${check_target}")" || cand_real=""
+    norm_slashes "${cand_real}"
+    cand_real="${NORM_OUT}"
+    if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
+        # Slug validation blocks textual traversal, but only successful
+        # canonicalization can rule out a symlink/junction escape.
+        return 1
+    fi
+    case "${cand_real}" in
+        "${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+# Portable mtime resolver. Tries GNU stat, BSD stat, BSD/macOS date -r,
+# python3, then perl. Returns "0" on full miss so callers can sort.
+mtime_of() {
+    target="$1"
+    out="$(stat -c '%Y' "${target}" 2>/dev/null)"
+    if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
+    out="$(stat -f '%m' "${target}" 2>/dev/null)"
+    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)"
+        if [ -n "${out}" ]; then printf "%s\n" "${out}"; return 0; fi
+    fi
+    printf "0\n"
+}
+
+resolve_from_env() {
+    plan_id="${PLAN_ID:-}"
+    slug_is_valid "${plan_id}" || return 1
+    candidate="${PLAN_ROOT}/${plan_id}"
+    if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
+        printf "%s\n" "${candidate}"
+        return 0
+    fi
+    return 1
+}
+
+resolve_from_active_file() {
+    [ -f "${ACTIVE_FILE}" ] || return 1
+    plan_id="$(tr -d '\r\n[:space:]' < "${ACTIVE_FILE}")"
+    # UTF-8 BOM is not part of the plan id. POSIX printf octal escapes keep
+    # this portable across GNU/BSD sed variants and Git-for-Windows sh.
+    utf8_bom="$(printf '\357\273\277')"
+    case "${plan_id}" in
+        "${utf8_bom}"*) plan_id="${plan_id#"${utf8_bom}"}" ;;
+    esac
+    slug_is_valid "${plan_id}" || return 1
+    candidate="${PLAN_ROOT}/${plan_id}"
+    if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
+        printf "%s\n" "${candidate}"
+        return 0
+    fi
+    return 1
+}
+
+resolve_latest_dir() {
+    [ -d "${PLAN_ROOT}" ] || return 1
+    # Portable newest-mtime selector. Skips hidden dirs, slug-invalid names,
+    # and dirs without task_plan.md (e.g. sessions/).
+    latest=""
+    latest_mtime=0
+    for entry in "${PLAN_ROOT}"/*/; do
+        [ -d "${entry}" ] || continue
+        clean="${entry%/}"
+        name="${clean##*/}"
+        case "${name}" in
+            .*) continue ;;
+        esac
+        slug_is_valid "${name}" || continue
+        [ -f "${clean}/task_plan.md" ] || continue
+        is_within_root "${clean}" || continue
+        mtime="$(mtime_of "${clean}")"
+        if [ "${mtime}" -gt "${latest_mtime}" ] 2>/dev/null; then
+            latest_mtime="${mtime}"
+            latest="${clean}"
+        fi
+    done
+    if [ -n "${latest}" ]; then
+        printf "%s\n" "${latest}"
+        return 0
+    fi
+    return 1
+}
+
+if resolve_from_env; then exit 0; fi
+if resolve_from_active_file; then exit 0; fi
+if resolve_latest_dir; then exit 0; fi
+exit 0