asimov

#!/usr/bin/env bash
set -Eeu -o pipefail

# Restrict permissions on all files/dirs we create (mktemp temp files, cache dir).
# Temp files contain the full home-directory layout, so keep them private (0600/0700).
umask 077

# Temp files for tracking excluded directory sizes and pre-existing exclusions.
ASIMOV_SIZE_LOG="$(mktemp)"
ASIMOV_EXCLUDED_CACHE="$(mktemp)"
ASIMOV_PATH_CACHE_TMP=""
trap 'rm -f "$ASIMOV_SIZE_LOG" "$ASIMOV_EXCLUDED_CACHE" "$ASIMOV_PATH_CACHE_TMP"' EXIT

# Look through the local filesystem and exclude development dependencies
# from Apple Time Machine backups.
#
# Since these files can be restored easily via their respective installation
# tools, there's no reason to waste time/bandwidth on backing them up.
#
# To retrieve a full list of excluded files, you may run:
#
#   sudo mdfind "com_apple_backup_excludeItem = 'com.apple.backupd'"
#
# For a full explanation, please see https://apple.stackexchange.com/a/25833/206772
#
# @author  Steve Grunwell
# @license MIT

# Keep ASIMOV_VERSION in sync with CHANGELOG and package managers (e.g. Homebrew).
readonly ASIMOV_VERSION='0.10.0'

print_usage() {
    printf 'Usage: asimov [--dry-run] [--verbose] [--quiet] [--stats] [--no-read-cache] [--no-write-cache] [directory]\n'
    printf '       asimov prune [--quiet]\n'
    printf '       asimov doctor [--quiet]\n'
    printf '\n'
    printf 'Exclude development dependency directories from Time Machine backups.\n'
    printf '\n'
    printf 'Commands:\n'
    printf '  prune              Report Time Machine exclusions whose directory no longer\n'
    printf '                     exists, and compact Asimov'\''s own cache. Read-only:\n'
    printf '                     it prints the removal command rather than running it\n'
    printf '  doctor             Check this install for problems: a shadowed binary, a\n'
    printf '                     leftover schedule, an unreadable cache, a bad config.\n'
    printf '                     Read-only; exits 1 if it finds anything\n'
    printf '\n'
    printf 'Options:\n'
    printf '  --dry-run          Print what would be excluded without changing Time Machine\n'
    printf '  --verbose          Show all directories including already-excluded ones\n'
    printf '  --quiet            Suppress all output except errors\n'
    printf '  --stats            Show directory sizes and total space in the summary\n'
    printf '  --no-read-cache    Ignore cached state; re-discover and re-verify everything (rebuilds the cache)\n'
    printf '  --no-write-cache   Run normally but do not persist any cache updates\n'
    printf '  --full-scan        Alias for --no-read-cache\n'
    printf '  --no-cache         Alias for --no-read-cache --no-write-cache (fully stateless run)\n'
    printf '  --help             Show this help and exit\n'
    printf '  --version          Show version and exit\n'
    printf '\n'
    printf 'Arguments:\n'
    printf '  directory          Directory to scan (default: home directory)\n'
    printf '\n'
    printf 'To scan additional directories on every run, add them to the config file\n'
    printf '(~/.config/asimov/config) under a [scan] section:\n'
    printf '\n'
    printf '  [scan]\n'
    printf '  extra = /private/var/www\n'
}

# Parse options (before we need ASIMOV_ROOT).
# Supports: --help, --version, --dry-run, --verbose, --quiet. Unknown options cause exit 1.
ASIMOV_DRY_RUN=
ASIMOV_VERBOSE=
ASIMOV_QUIET=
ASIMOV_STATS=
ASIMOV_NO_READ_CACHE=
ASIMOV_NO_WRITE_CACHE=
ASIMOV_SCAN_DIR=

# Subcommands are recognised only as the first argument, so that a directory
# sharing the name stays reachable as `asimov ./prune`.
ASIMOV_COMMAND=scan
case "${1:-}" in
    prune)  ASIMOV_COMMAND=prune;  shift ;;
    doctor) ASIMOV_COMMAND=doctor; shift ;;
esac
readonly ASIMOV_COMMAND

for arg in "$@"; do
    case "$arg" in
        --dry-run)    ASIMOV_DRY_RUN=1 ;;
        --verbose)    ASIMOV_VERBOSE=1 ;;
        --quiet)      ASIMOV_QUIET=1 ;;
        --stats)      ASIMOV_STATS=1 ;;
        # Cache controls along two axes. --full-scan and --no-cache are kept as
        # back-compat aliases: --full-scan = --no-read-cache; --no-cache = both.
        --no-read-cache)  ASIMOV_NO_READ_CACHE=1 ;;
        --no-write-cache) ASIMOV_NO_WRITE_CACHE=1 ;;
        --full-scan)  ASIMOV_NO_READ_CACHE=1 ;;
        --no-cache)   ASIMOV_NO_READ_CACHE=1; ASIMOV_NO_WRITE_CACHE=1 ;;
        --help)       print_usage; exit 0 ;;
        --version)    printf '%s\n' "$ASIMOV_VERSION"; exit 0 ;;
        -*)
            echo "asimov: unknown option '$arg'" >&2
            print_usage >&2
            exit 1
            ;;
        *)
            ASIMOV_SCAN_DIR="$arg"
            ;;
    esac
done
readonly ASIMOV_DRY_RUN
readonly ASIMOV_VERBOSE
readonly ASIMOV_QUIET
readonly ASIMOV_STATS
readonly ASIMOV_NO_READ_CACHE
readonly ASIMOV_NO_WRITE_CACHE

if [[ -n "$ASIMOV_QUIET" && -n "$ASIMOV_VERBOSE" ]]; then
    echo "asimov: --quiet and --verbose are mutually exclusive" >&2
    exit 1
fi

# Named constants for size formatting.
readonly ASIMOV_KB_PER_MB=1024
readonly ASIMOV_KB_PER_GB=1048576

# Disable colors when stdout is not a terminal (e.g. launchd, pipes, redirects).
if [[ -t 1 ]]; then
    readonly ASIMOV_COLOR_INFO=$'\033[0;36m'
    readonly ASIMOV_COLOR_SUCCESS=$'\033[0;32m'
    readonly ASIMOV_COLOR_DIM=$'\033[0;90m'
    readonly ASIMOV_COLOR_RESET=$'\033[0m'
else
    readonly ASIMOV_COLOR_INFO=''
    readonly ASIMOV_COLOR_SUCCESS=''
    readonly ASIMOV_COLOR_DIM=''
    readonly ASIMOV_COLOR_RESET=''
fi

# Print a dim timestamped debug line when --verbose is set.
# Uses bash's built-in $SECONDS variable (auto-increments from 0 at script start).
# Output goes to stderr so it stays visible even when stdout is redirected
# (e.g. inside discover_new_paths_via_mdfind whose stdout is captured to a file).
verbose_timing() {
    [[ -n "$ASIMOV_VERBOSE" ]] || return 0
    printf '%s  [%ds] %s%s\n' "$ASIMOV_COLOR_DIM" "$SECONDS" "$1" "$ASIMOV_COLOR_RESET" >&2
}

# Resolve the root directory to scan (console user's home when running as root).
resolve_asimov_root() {
    if [[ "${EUID:-$(id -u)}" -eq 0 ]]; then
        local console_user
        console_user="$(stat -f '%Su' /dev/console 2>/dev/null || echo '')"
        if [[ -n "$console_user" && "$console_user" != "root" ]]; then
            local root_dir
            root_dir="$(dscl . -read "/Users/${console_user}" NFSHomeDirectory 2>/dev/null | awk '{print $2}')"
            if [[ -n "$root_dir" ]]; then
                echo "$root_dir"
                return
            fi
        fi
        echo ~
    else
        echo ~
    fi
}

ASIMOV_ROOT="$(resolve_asimov_root)"
readonly ASIMOV_ROOT
readonly ASIMOV_EXCLUDED_STATE="${ASIMOV_ROOT}/.cache/asimov/excluded"
readonly ASIMOV_FAILED_STATE="${ASIMOV_ROOT}/.cache/asimov/failed"
readonly ASIMOV_MDFIND_SEEN="${ASIMOV_ROOT}/.cache/asimov/mdfind_seen"
readonly ASIMOV_PATH_CACHE="${ASIMOV_ROOT}/.cache/asimov/paths"
readonly ASIMOV_CACHE_DIR="${ASIMOV_ROOT}/.cache/asimov"

# --- cache resilience ---
#
# Every cache file is an optimisation: a run must survive one being unreadable
# or unwritable rather than aborting. Without these guards a bare `cat` on an
# unreadable state file fails under `set -Eeu -o pipefail` and kills the whole
# run, printing nothing but "Permission denied" (see issue #122).
#
# The usual cause is a run as root — `sudo asimov`, or a schedule installed as
# root — leaving root-owned files behind for the next run as the user.
ASIMOV_CACHE_WARNED=

# Warn once per run that the cache is unusable, and name the fix. Always goes to
# stderr, including under --quiet: this is a degraded run, not routine chatter.
warn_unusable_cache() {
    [[ -n "$ASIMOV_CACHE_WARNED" ]] && return 0
    ASIMOV_CACHE_WARNED=1
    printf '! %s is not %s — continuing without the cache.\n' "$1" "$2" >&2
    printf '  This usually means a previous run as root left root-owned files behind.\n' >&2
    printf '  To reset it:\n\n    rm -rf %s\n\n' "$ASIMOV_CACHE_DIR" >&2
    return 0
}

# True when a state file exists and can be read. A missing file is not an error
# (there is simply nothing cached yet), so it returns false without warning.
cache_readable() {
    [[ -f "$1" ]] || return 1
    [[ -r "$1" ]] && return 0
    warn_unusable_cache "$1" "readable"
    return 1
}

# True when a state file can be written to, creating it if necessary. An absent
# file is writable when its directory is.
cache_writable() {
    if [[ -e "$1" ]]; then
        [[ -w "$1" ]] && return 0
        warn_unusable_cache "$1" "writable"
        return 1
    fi
    [[ -d "$ASIMOV_CACHE_DIR" && -w "$ASIMOV_CACHE_DIR" ]] && return 0
    [[ -d "$ASIMOV_CACHE_DIR" ]] || return 1   # not created yet; ensure_cache_dir reports
    warn_unusable_cache "$ASIMOV_CACHE_DIR" "writable"
    return 1
}

# Append a line to a state file, skipping silently when it isn't writable.
# Always returns 0 so callers can use it as the tail of an && list under set -e.
append_state() {
    cache_writable "$2" || return 0
    printf '%s\n' "$1" >> "$2" 2>/dev/null || true
    return 0
}

# Time Machine's system preferences, home of the "sticky" path exclusion list
# (tmutil addexclusion -p). Overridable so tests can point at a fixture.
readonly ASIMOV_TM_PLIST="${ASIMOV_TM_PLIST:-/Library/Preferences/com.apple.TimeMachine.plist}"

# --- prune ---
#
# Asimov's own exclusions cannot go stale. `tmutil addexclusion PATH` stores the
# exclusion as an extended attribute on the directory itself, so deleting the
# directory deletes the exclusion with it.
#
# What *does* go stale is the "sticky" list: `tmutil addexclusion -p PATH` records
# the path in Time Machine's system preferences instead, and that entry survives
# the directory forever. Asimov has never written to that list, but other tools
# and manual commands do, and nothing surfaces the leftovers.

# Resolve a "~user/…" path, as stored in Time Machine's preferences, to an
# absolute one. Falls back to /Users/<name> when the account can't be read.
expand_tm_path() {
    local path="$1" user rest home
    case "$path" in
        '~'*) ;;
        *) printf '%s\n' "$path"; return 0 ;;
    esac
    path="${path#\~}"
    user="${path%%/*}"
    rest="${path#"$user"}"
    if [[ -z "$user" ]]; then
        printf '%s\n' "${ASIMOV_ROOT}${rest}"
        return 0
    fi
    home="$(dscl . -read "/Users/${user}" NFSHomeDirectory 2>/dev/null | sed -n 's/^NFSHomeDirectory: //p')"
    [[ -n "$home" ]] || home="/Users/${user}"
    printf '%s\n' "${home}${rest}"
}

# Print the sticky exclusion list, one raw path per line.
# `defaults` renders it as a plist array; strip the parentheses, indentation,
# trailing commas, and surrounding quotes.
read_sticky_exclusions() {
    [[ -r "$ASIMOV_TM_PLIST" ]] || return 0
    defaults read "${ASIMOV_TM_PLIST%.plist}" SkipPaths 2>/dev/null \
        | sed -e '/^[[:space:]]*[()]/d' \
              -e 's/^[[:space:]]*//' \
              -e 's/[[:space:]]*,$//' \
              -e 's/^"//' -e 's/"$//' \
        | grep -v '^$' || true
}

# Drop entries whose directory no longer exists from Asimov's path cache.
# Echoes the number of entries removed. This only ever touches Asimov's own
# file under ~/.cache/asimov.
prune_path_cache() {
    cache_readable "$ASIMOV_PATH_CACHE" || { echo 0; return 0; }
    cache_writable "$ASIMOV_PATH_CACHE" || { echo 0; return 0; }

    # A brace group with a redirect runs in the current shell, so the counters
    # below survive the loop.
    local tmp line dropped=0
    tmp="${ASIMOV_PATH_CACHE}.tmp.$$"
    {
        printf '# asimov path cache — updated %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
        while IFS= read -r line; do
            [[ "$line" =~ ^# ]] && continue
            [[ -z "$line" ]] && continue
            if [[ -d "$line" ]]; then
                printf '%s\n' "$line"
            else
                dropped=$((dropped + 1))
            fi
        done < "$ASIMOV_PATH_CACHE"
    } > "$tmp"

    mv -f "$tmp" "$ASIMOV_PATH_CACHE"
    echo "$dropped"
}

cmd_prune() {
    local raw expanded sticky_total=0
    local stale_paths="" stale_count=0

    while IFS= read -r raw; do
        sticky_total=$((sticky_total + 1))
        expanded="$(expand_tm_path "$raw")"
        if [[ ! -e "$expanded" ]]; then
            stale_count=$((stale_count + 1))
            stale_paths="${stale_paths}${raw}"$'\n'
        fi
    done < <(read_sticky_exclusions)

    local cache_dropped
    cache_dropped="$(prune_path_cache)"

    [[ -n "$ASIMOV_QUIET" ]] && return 0

    if [[ "$stale_count" -gt 0 ]]; then
        printf '\n%sStale Time Machine exclusions (%s):%s\n' \
            "$ASIMOV_COLOR_INFO" "$stale_count" "$ASIMOV_COLOR_RESET"
        printf '%s' "$stale_paths" | while IFS= read -r raw; do
            [[ -z "$raw" ]] && continue
            printf '  %s %spath no longer exists%s\n' \
                "$raw" "$ASIMOV_COLOR_DIM" "$ASIMOV_COLOR_RESET"
        done
        printf '\nThese are sticky exclusions (%stmutil addexclusion -p%s), which Asimov never sets.\n' \
            "$ASIMOV_COLOR_DIM" "$ASIMOV_COLOR_RESET"
        printf 'They persist after the directory is deleted. To remove one:\n\n'
        printf '  sudo tmutil removeexclusion -p %s\n\n' "$(printf '%s' "$stale_paths" | head -1)"
    elif [[ "$sticky_total" -gt 0 ]]; then
        printf '\n%s✓%s No stale exclusions. All %s sticky entries point at directories that exist.\n' \
            "$ASIMOV_COLOR_SUCCESS" "$ASIMOV_COLOR_RESET" "$sticky_total"
    else
        printf '\n%s✓%s No sticky Time Machine exclusions are set on this Mac.\n' \
            "$ASIMOV_COLOR_SUCCESS" "$ASIMOV_COLOR_RESET"
    fi

    if [[ "$cache_dropped" -gt 0 ]]; then
        printf 'Asimov cache: %s stale %s dropped.\n' \
            "$cache_dropped" "$([[ "$cache_dropped" -eq 1 ]] && echo entry || echo entries)"
    else
        printf 'Asimov cache: nothing to prune.\n'
    fi

    printf '\n%sAsimov'\''s own exclusions are stored on the directory itself, so they are\nremoved automatically when you delete it — only sticky entries can outlive it.%s\n' \
        "$ASIMOV_COLOR_DIM" "$ASIMOV_COLOR_RESET"
}

if [[ "$ASIMOV_COMMAND" == "prune" ]]; then
    cmd_prune
    exit 0
fi

# --- doctor ---
#
# Diagnoses an install rather than changing it. The failure modes it looks for
# are the ones people hit coming from v0.3.0 (issue #122): an old binary still
# first on PATH, a LaunchAgent pointing at a Homebrew cellar that no longer
# exists, and a cache left root-owned by a run as root.
#
# Two rules keep it safe to run at any point in a migration:
#   - It never writes anything. Fixes are printed, never applied.
#   - It never executes another asimov binary it finds. v0.3.0 parses no
#     arguments at all, so running it to ask its version would start a real
#     scan; versions are read out of the file instead.

# The label a current install schedules itself under. Everything else in the
# list below is a leftover to be removed, never re-loaded.
readonly ASIMOV_CURRENT_LABEL='com.stevegrunwell.asimov'

# Every known LaunchAgent label Asimov has ever shipped under, plus Homebrew's.
readonly ASIMOV_DOCTOR_LABELS=(
    'com.stevegrunwell.asimov'   # current, and the original
    'com.django23.asimov'        # the v0.4.x–v0.8.0 fork
    'homebrew.mxcl.asimov'       # brew services
)

ASIMOV_DOCTOR_PROBLEMS=0

doctor_heading() {
    [[ -n "$ASIMOV_QUIET" ]] && return 0
    printf '\n%s%s%s\n' "$ASIMOV_COLOR_INFO" "$1" "$ASIMOV_COLOR_RESET"
    return 0
}

doctor_ok() {
    [[ -n "$ASIMOV_QUIET" ]] && return 0
    printf '  %s✓%s %s\n' "$ASIMOV_COLOR_SUCCESS" "$ASIMOV_COLOR_RESET" "$1"
    return 0
}

doctor_note() {
    [[ -n "$ASIMOV_QUIET" ]] && return 0
    printf '  %s·%s %s\n' "$ASIMOV_COLOR_DIM" "$ASIMOV_COLOR_RESET" "$1"
    return 0
}

# Problems print even under --quiet: a silent doctor that found something is
# worse than useless in a cron job.
doctor_problem() {
    ASIMOV_DOCTOR_PROBLEMS=$((ASIMOV_DOCTOR_PROBLEMS + 1))
    printf '  ✗ %s\n' "$1"
    return 0
}

# Print a command the user can copy to fix the problem just reported.
doctor_fix() {
    printf '      %s%s%s\n' "$ASIMOV_COLOR_DIM" "$1" "$ASIMOV_COLOR_RESET"
    return 0
}

# Resolve a path to its physical location, symlinks and all. Homebrew installs
# asimov as a symlink into the cellar, so comparing raw paths would report a
# shadow that isn't there.
doctor_realpath() {
    local path="$1" dir base
    dir="$(cd "$(dirname "$path")" 2>/dev/null && pwd -P)" || { printf '%s\n' "$path"; return 0; }
    base="$(basename "$path")"
    while [[ -L "${dir}/${base}" ]]; do
        local target
        target="$(readlink "${dir}/${base}")"
        case "$target" in
            /*) dir="$(cd "$(dirname "$target")" 2>/dev/null && pwd -P)" || break ;;
            *)  dir="$(cd "$dir" && cd "$(dirname "$target")" 2>/dev/null && pwd -P)" || break ;;
        esac
        base="$(basename "$target")"
    done
    printf '%s/%s\n' "$dir" "$base"
}

# Read a version out of an asimov script without running it. Handles both the
# current `readonly ASIMOV_VERSION='x'` and v0.3.0's `# @version x` header.
doctor_file_version() {
    local file="$1" line
    line="$(grep -m1 -E "^readonly ASIMOV_VERSION=|^# @version " "$file" 2>/dev/null || true)"
    [[ -n "$line" ]] || { printf 'unknown\n'; return 0; }
    line="${line##*@version }"
    line="${line##*=}"
    line="${line//\'/}"
    line="${line//\"/}"
    line="${line#"${line%%[![:space:]]*}"}"
    line="${line%"${line##*[![:space:]]}"}"
    printf '%s\n' "${line:-unknown}"
}

# Every `asimov` on PATH, in PATH order, deduplicated by physical path.
doctor_path_binaries() {
    local dir candidate resolved seen=""
    while IFS= read -r dir; do
        [[ -n "$dir" ]] || continue
        candidate="${dir}/asimov"
        [[ -x "$candidate" && ! -d "$candidate" ]] || continue
        resolved="$(doctor_realpath "$candidate")"
        case "$seen" in
            *"|${resolved}|"*) continue ;;
        esac
        seen="${seen}|${resolved}|"
        printf '%s\n' "$resolved"
    done < <(printf '%s\n' "${PATH//:/$'\n'}")
}

doctor_check_install() {
    doctor_heading 'Install'

    local running
    running="$(doctor_realpath "${BASH_SOURCE[0]}")"
    doctor_ok "asimov ${ASIMOV_VERSION} (${running})"

    local -a found=()
    while IFS= read -r line; do
        [[ -n "$line" ]] && found+=("$line")
    done < <(doctor_path_binaries)

    if [[ ${#found[@]} -eq 0 ]]; then
        doctor_note "no asimov on PATH — you are running it by path"
        return 0
    fi

    local first="${found[0]}"
    if [[ "$first" != "$running" ]]; then
        doctor_problem "typing 'asimov' runs a different binary — this one is shadowed"
        doctor_fix "${first}  (version $(doctor_file_version "$first"))"
        doctor_fix "Remove the one you don't want, or fix the order of PATH."
    else
        doctor_ok "'asimov' on PATH is this one"
    fi

    local other
    for other in "${found[@]}"; do
        [[ "$other" == "$first" ]] && continue
        doctor_note "also installed: ${other} (version $(doctor_file_version "$other"))"
    done
    return 0
}

doctor_check_schedule() {
    doctor_heading 'Schedule'

    local agents_dir="${ASIMOV_ROOT}/Library/LaunchAgents"
    local label plist program active=0

    for label in "${ASIMOV_DOCTOR_LABELS[@]}"; do
        plist="${agents_dir}/${label}.plist"
        [[ -f "$plist" ]] || continue
        active=$((active + 1))

        program="$(plutil -extract Program raw "$plist" 2>/dev/null || true)"
        if [[ -n "$program" && ! -x "$program" ]]; then
            doctor_problem "${label}: its program ${program} no longer exists"
            doctor_fix "launchctl bootout gui/\$(id -u)/${label}"
            doctor_fix "rm ${plist}"
            continue
        fi

        if launchctl list "$label" >/dev/null 2>&1; then
            doctor_ok "${label} — loaded, runs daily"
        elif [[ "$label" == "$ASIMOV_CURRENT_LABEL" ]]; then
            doctor_problem "${label}: installed but not loaded, so it never runs"
            doctor_fix "launchctl bootstrap gui/\$(id -u) ${plist}"
        else
            # A label we no longer ship, sitting unloaded: a leftover from an
            # older install. Loading it is never the right advice.
            doctor_problem "${label}: leftover from an older install, not loaded"
            doctor_fix "rm ${plist}"
        fi
    done

    if [[ "$active" -eq 0 ]]; then
        doctor_note "not scheduled — Asimov only runs when you run it"
    elif [[ "$active" -gt 1 ]]; then
        doctor_problem "more than one schedule is installed (${active}) — they will both run"
        doctor_fix "Keep com.stevegrunwell.asimov and bootout the rest."
    fi
    return 0
}

# Humanise an age in seconds: "3 minutes ago", "2 days ago".
doctor_humanise_age() {
    local seconds="$1" value unit
    if   [[ "$seconds" -lt 60 ]];    then printf 'just now\n'; return 0
    elif [[ "$seconds" -lt 3600 ]];  then value=$((seconds / 60));    unit=minute
    elif [[ "$seconds" -lt 86400 ]]; then value=$((seconds / 3600));  unit=hour
    else                                  value=$((seconds / 86400)); unit=day
    fi
    printf '%s %s%s ago\n' "$value" "$unit" "$([[ "$value" -eq 1 ]] || echo s)"
}

doctor_check_cache() {
    doctor_heading 'Cache'

    if [[ ! -d "$ASIMOV_CACHE_DIR" ]]; then
        doctor_ok "no cache yet — the next run builds one"
        return 0
    fi

    if [[ ! -w "$ASIMOV_CACHE_DIR" ]]; then
        doctor_problem "${ASIMOV_CACHE_DIR} is not writable by you"
        doctor_fix "rm -rf ${ASIMOV_CACHE_DIR}"
        return 0
    fi

    local file owner broken=0 root_owned=0
    for file in "$ASIMOV_EXCLUDED_STATE" "$ASIMOV_FAILED_STATE" \
                "$ASIMOV_MDFIND_SEEN" "$ASIMOV_PATH_CACHE"; do
        [[ -e "$file" ]] || continue
        if [[ ! -r "$file" || ! -w "$file" ]]; then
            broken=$((broken + 1))
            owner="$(stat -f '%Su' "$file" 2>/dev/null || echo 'unknown')"
            [[ "$owner" == "root" ]] && root_owned=$((root_owned + 1))
            doctor_problem "${file} is not readable and writable by you (owner: ${owner})"
        fi
    done

    if [[ "$broken" -gt 0 ]]; then
        # Only name root as the cause when root actually owns something: a
        # diagnosis that guesses wrong sends people chasing the wrong fix.
        if [[ "$root_owned" -gt 0 ]]; then
            doctor_fix "A run as root left these behind. Clear them:"
        else
            doctor_fix "Asimov can't use these. Clear them:"
        fi
        doctor_fix "rm -rf ${ASIMOV_CACHE_DIR}"
        return 0
    fi

    if [[ -r "$ASIMOV_PATH_CACHE" ]]; then
        local entries age
        entries="$(grep -cve '^#' -e '^$' "$ASIMOV_PATH_CACHE" 2>/dev/null || true)"
        doctor_ok "${entries:-0} cached paths"
        age="$(( $(date +%s) - $(stat -f '%m' "$ASIMOV_PATH_CACHE" 2>/dev/null || date +%s) ))"
        doctor_ok "last scan: $(doctor_humanise_age "$age")"
    else
        doctor_ok "cache is readable, no scan recorded yet"
    fi
    return 0
}

doctor_check_config() {
    doctor_heading 'Config'

    local config_file="${ASIMOV_ROOT}/.config/asimov/config"
    if [[ ! -f "$config_file" ]]; then
        doctor_note "no config file — using defaults"
        return 0
    fi
    if [[ ! -r "$config_file" ]]; then
        doctor_problem "${config_file} is not readable by you"
        return 0
    fi

    # Same grammar load_config accepts, but here anything unrecognised is
    # reported instead of silently ignored — a typo'd key is invisible otherwise.
    local section="" line key unknown=0
    while IFS= read -r line || [[ -n "$line" ]]; do
        line="${line%%#*}"
        line="${line#"${line%%[![:space:]]*}"}"
        line="${line%"${line##*[![:space:]]}"}"
        [[ -z "$line" ]] && continue

        if [[ "$line" =~ ^\[([a-z_]+)\]$ ]]; then
            section="${BASH_REMATCH[1]}"
            case "$section" in
                fixed_dirs|scan|sentinels) ;;
                *)
                    unknown=$((unknown + 1))
                    doctor_problem "unknown section [${section}] in ${config_file}"
                    ;;
            esac
            continue
        fi

        if [[ "$line" =~ ^([a-z_]+)[[:space:]]*=[[:space:]]*(.*)$ ]]; then
            key="${BASH_REMATCH[1]}"
            case "${section}:${key}" in
                fixed_dirs:enabled|fixed_dirs:extra|scan:extra|\
                sentinels:extra|sentinels:disabled) ;;
                *)
                    # A key under an already-reported section is the same fault.
                    case "$section" in
                        fixed_dirs|scan|sentinels)
                            unknown=$((unknown + 1))
                            doctor_problem "unknown key '${key}' under [${section}] in ${config_file}"
                            ;;
                    esac
                    ;;
            esac
        fi
    done < "$config_file"

    [[ "$unknown" -eq 0 ]] && doctor_ok "${config_file} looks valid"
    return 0
}

doctor_check_time_machine() {
    doctor_heading 'Time Machine'

    if ! command -v tmutil >/dev/null 2>&1; then
        doctor_problem "tmutil not found — is this macOS?"
        return 0
    fi

    if tmutil isexcluded "$ASIMOV_ROOT" >/dev/null 2>&1; then
        doctor_ok "tmutil can read exclusions"
    else
        doctor_problem "tmutil cannot read exclusions — grant your terminal Full Disk Access"
        doctor_fix "System Settings → Privacy & Security → Full Disk Access"
    fi
    return 0
}

cmd_doctor() {
    [[ -n "$ASIMOV_QUIET" ]] || printf '\n%sAsimov doctor%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"

    doctor_check_install
    doctor_check_schedule
    doctor_check_cache
    doctor_check_config
    doctor_check_time_machine

    if [[ "$ASIMOV_DOCTOR_PROBLEMS" -eq 0 ]]; then
        [[ -n "$ASIMOV_QUIET" ]] || printf '\n%s✓%s No problems found.\n\n' \
            "$ASIMOV_COLOR_SUCCESS" "$ASIMOV_COLOR_RESET"
        return 0
    fi

    printf '\n%s problem%s found.\n\n' "$ASIMOV_DOCTOR_PROBLEMS" \
        "$([[ "$ASIMOV_DOCTOR_PROBLEMS" -eq 1 ]] || echo s)"
    return 1
}

if [[ "$ASIMOV_COMMAND" == "doctor" ]]; then
    cmd_doctor
    exit $?
fi

# Load optional config from ~/.config/asimov/config.
# Populates ASIMOV_CONFIG_* variables. Missing file is silently ignored.
load_config() {
    local config_file="${ASIMOV_ROOT}/.config/asimov/config"

    ASIMOV_CONFIG_FIXED_DIRS_ENABLED=false
    ASIMOV_CONFIG_EXTRA_FIXED_DIRS=()
    ASIMOV_CONFIG_EXTRA_SENTINELS=()
    ASIMOV_CONFIG_DISABLED_SENTINELS=()
    ASIMOV_CONFIG_SCAN_DIRS=()

    [[ -f "$config_file" ]] || return 0

    local section="" line key value
    while IFS= read -r line || [[ -n "$line" ]]; do
        line="${line%%#*}"
        line="${line#"${line%%[![:space:]]*}"}"
        line="${line%"${line##*[![:space:]]}"}"
        [[ -z "$line" ]] && continue

        if [[ "$line" =~ ^\[([a-z_]+)\]$ ]]; then
            section="${BASH_REMATCH[1]}"
            continue
        fi

        if [[ "$line" =~ ^([a-z_]+)[[:space:]]*=[[:space:]]*(.*)$ ]]; then
            key="${BASH_REMATCH[1]}"
            value="${BASH_REMATCH[2]}"
            value="${value%"${value##*[![:space:]]}"}"

            case "${section}:${key}" in
                fixed_dirs:enabled)
                    ASIMOV_CONFIG_FIXED_DIRS_ENABLED="$value"
                    ;;
                fixed_dirs:extra)
                    value="${value/#\~/$HOME}"
                    ASIMOV_CONFIG_EXTRA_FIXED_DIRS+=("$value")
                    ;;
                scan:extra)
                    value="${value/#\~/$HOME}"
                    ASIMOV_CONFIG_SCAN_DIRS+=("$value")
                    ;;
                sentinels:extra)
                    ASIMOV_CONFIG_EXTRA_SENTINELS+=("$value")
                    ;;
                sentinels:disabled)
                    ASIMOV_CONFIG_DISABLED_SENTINELS+=("$value")
                    ;;
            esac
        fi
    done < "$config_file"
}

load_config

# Resolve the set of directories to scan into ASIMOV_SCAN_DIRS.
#   - A positional CLI argument overrides everything: scan only that directory.
#   - Otherwise scan the home directory plus any [scan] extra dirs from config.
# Configured dirs that don't exist are warned about and skipped rather than
# aborting the run (e.g. an unmounted external volume).
ASIMOV_SCAN_DIRS=()
if [[ -n "$ASIMOV_SCAN_DIR" ]]; then
    if [[ ! -d "$ASIMOV_SCAN_DIR" ]]; then
        echo "asimov: not a directory: ${ASIMOV_SCAN_DIR}" >&2
        exit 1
    fi
    ASIMOV_SCAN_DIRS=("$ASIMOV_SCAN_DIR")
else
    ASIMOV_SCAN_DIRS=("$ASIMOV_ROOT")
    for scan_dir in ${ASIMOV_CONFIG_SCAN_DIRS[@]+"${ASIMOV_CONFIG_SCAN_DIRS[@]}"}; do
        if [[ ! -d "$scan_dir" ]]; then
            [[ -z "$ASIMOV_QUIET" ]] && \
                echo "asimov: configured scan directory does not exist, skipping: ${scan_dir}" >&2
            continue
        fi
        ASIMOV_SCAN_DIRS+=("$scan_dir")
    done
fi

# Drop any scan dir that equals or nests inside another (Time Machine exclusions
# and find traversal are both recursive, so the parent already covers it). This
# also collapses exact duplicates, e.g. a configured ~/Projects under $HOME.
prune_nested_scan_dirs() {
    local -a kept=()
    local dir other nested dup k
    for dir in "${ASIMOV_SCAN_DIRS[@]}"; do
        nested=false
        for other in "${ASIMOV_SCAN_DIRS[@]}"; do
            [[ "$dir" == "$other" ]] && continue
            if [[ "$dir" == "$other"/* ]]; then nested=true; break; fi
        done
        [[ "$nested" == true ]] && continue
        dup=false
        for k in ${kept[@]+"${kept[@]}"}; do
            [[ "$k" == "$dir" ]] && { dup=true; break; }
        done
        [[ "$dup" == true ]] && continue
        kept+=("$dir")
    done
    ASIMOV_SCAN_DIRS=("${kept[@]}")
}
prune_nested_scan_dirs
readonly -a ASIMOV_SCAN_DIRS

# When ignoring cached reads but still writing (e.g. --full-scan / --no-read-cache),
# clear the append-only state so the rebuilt cache reflects only this run's results.
# When not writing (--no-cache / --no-write-cache), leave every cache file untouched.
# (The paths cache is truncated separately by init_path_cache before the full scan.)
if [[ -n "$ASIMOV_NO_READ_CACHE" && -z "$ASIMOV_NO_WRITE_CACHE" ]]; then
    rm -f "$ASIMOV_EXCLUDED_STATE" "$ASIMOV_FAILED_STATE" "$ASIMOV_MDFIND_SEEN" 2>/dev/null || true
fi

# Build a cache of paths already excluded from Time Machine.
# Merges Spotlight index (what macOS reports) with our own persistent state
# (written after each successful tmutil call). The persistent state handles:
#   - Interrupted runs (Ctrl+C before all tmutil calls complete)
#   - Spotlight indexing delays (tmutil sets xattr but Spotlight hasn't indexed it)
verbose_timing "Building excluded-path cache via Spotlight…"
: > "$ASIMOV_EXCLUDED_CACHE"
for scan_dir in "${ASIMOV_SCAN_DIRS[@]}"; do
    mdfind -onlyin "$scan_dir" "com_apple_backup_excludeItem = 'com.apple.backupd'" 2>/dev/null \
        >> "$ASIMOV_EXCLUDED_CACHE" || true
done
sort -u -o "$ASIMOV_EXCLUDED_CACHE" "$ASIMOV_EXCLUDED_CACHE"
spotlight_count="$(wc -l < "$ASIMOV_EXCLUDED_CACHE" | tr -d ' ')"
# Merge persistent excluded + failed state into the Spotlight cache.
# Failed paths (e.g. read-only dirs inside Go's module cache) are included so the bulk filter
# skips them instantly instead of wasting time retrying tmutil.
# Skipped under --no-read-cache (--full-scan / --no-cache): every path is then
# re-verified against the tmutil isexcluded ground truth instead.
if [[ -z "$ASIMOV_NO_READ_CACHE" ]] && { cache_readable "$ASIMOV_EXCLUDED_STATE" || cache_readable "$ASIMOV_FAILED_STATE"; }; then
    {
        cat "$ASIMOV_EXCLUDED_CACHE"
        if cache_readable "$ASIMOV_EXCLUDED_STATE"; then cat "$ASIMOV_EXCLUDED_STATE"; fi
        if cache_readable "$ASIMOV_FAILED_STATE"; then cat "$ASIMOV_FAILED_STATE"; fi
    } | sort -u > "${ASIMOV_EXCLUDED_CACHE}.merged"
    mv -f "${ASIMOV_EXCLUDED_CACHE}.merged" "$ASIMOV_EXCLUDED_CACHE"
fi
verbose_timing "Excluded-path cache ready ($(wc -l < "$ASIMOV_EXCLUDED_CACHE" | tr -d ' ') entries, ${spotlight_count} from Spotlight)"

# --- Path cache ---
# (ASIMOV_PATH_CACHE is defined alongside the other state files, above, so that
# the prune subcommand can reach it before any of the scan machinery runs.)

# Create the cache directory, chown to console user when running as root.
ensure_cache_dir() {
    if [[ ! -d "$ASIMOV_CACHE_DIR" ]]; then
        mkdir -p "$ASIMOV_CACHE_DIR" 2>/dev/null || {
            warn_unusable_cache "$ASIMOV_CACHE_DIR" "writable"
            return 0
        }
    fi
    if [[ "${EUID:-$(id -u)}" -eq 0 ]]; then
        local console_user
        console_user="$(stat -f '%Su' /dev/console 2>/dev/null || echo '')"
        if [[ -n "$console_user" && "$console_user" != "root" ]]; then
            # Create the state files *before* the chown. Appending to an existing
            # file never changes its owner, so every write later in this root run
            # lands in a file the console user can still read next time. Chowning
            # only the directory (as this did before) left root-owned files behind
            # that broke the following user run outright — issue #122.
            touch "$ASIMOV_EXCLUDED_STATE" "$ASIMOV_FAILED_STATE" \
                  "$ASIMOV_MDFIND_SEEN" "$ASIMOV_PATH_CACHE" 2>/dev/null || true
            chown -R "$console_user" "$ASIMOV_CACHE_DIR" 2>/dev/null || true
        fi
    fi
    return 0
}

# Read cached paths, filtering to those that still exist as directories
# and fall under one of the scan dirs. Outputs valid paths to stdout.
read_path_cache() {
    cache_readable "$ASIMOV_PATH_CACHE" || return 0
    local line d in_scope
    while IFS= read -r line; do
        # Skip comments and blank lines
        [[ "$line" =~ ^#  ]] && continue
        [[ -z "$line" ]] && continue
        # Must still exist as a directory
        [[ -d "$line" ]] || continue
        # Must be under one of the scan dirs
        in_scope=false
        for d in "${ASIMOV_SCAN_DIRS[@]}"; do
            if [[ "$line" == "${d}"/* || "$line" == "${d}" ]]; then in_scope=true; break; fi
        done
        [[ "$in_scope" == true ]] || continue
        printf '%s\n' "$line"
    done < "$ASIMOV_PATH_CACHE"
}

# Initialize the path cache file with a header, truncating any old contents.
# No-op if --dry-run or writes are disabled (--no-write-cache / --no-cache).
init_path_cache() {
    [[ -n "$ASIMOV_DRY_RUN" || -n "$ASIMOV_NO_WRITE_CACHE" ]] && return 0
    ensure_cache_dir
    cache_writable "$ASIMOV_PATH_CACHE" || return 0
    printf '# asimov path cache — updated %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" > "$ASIMOV_PATH_CACHE"
}

# Append a single path to the cache file. No-op if --dry-run or writes are disabled (--no-write-cache / --no-cache).
append_path_to_cache() {
    [[ -n "$ASIMOV_DRY_RUN" || -n "$ASIMOV_NO_WRITE_CACHE" ]] && return 0
    append_state "$1" "$ASIMOV_PATH_CACHE"
}

# Remove paths that are descendants of other paths in the list.
# Expects sorted input. Outputs only outermost (non-nested) paths.
# Example: /a/node_modules and /a/node_modules/foo/node_modules → keeps only /a/node_modules
# (Time Machine exclusions are recursive, so the descendant is already covered.)
dedup_nested_paths() {
    local last_kept="" path
    while IFS= read -r path; do
        [[ -z "$path" ]] && continue
        if [[ -n "$last_kept" && "$path" == "${last_kept}/"* ]]; then
            continue
        fi
        printf '%s\n' "$path"
        last_kept="$path"
    done
}

# Sort, deduplicate, and prune stale entries from the cache file.
# Writes atomically via temp file + mv. No-op if --dry-run or writes are disabled (--no-write-cache / --no-cache).
finalize_path_cache() {
    [[ -n "$ASIMOV_DRY_RUN" || -n "$ASIMOV_NO_WRITE_CACHE" ]] && return 0
    cache_readable "$ASIMOV_PATH_CACHE" || return 0
    cache_writable "$ASIMOV_PATH_CACHE" || return 0

    ASIMOV_PATH_CACHE_TMP="${ASIMOV_PATH_CACHE}.tmp.$$"
    {
        printf '# asimov path cache — updated %s\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
        # Keep only lines that are existing directories, sorted and deduplicated
        while IFS= read -r line; do
            [[ "$line" =~ ^# ]] && continue
            [[ -z "$line" ]] && continue
            if [[ -d "$line" ]]; then
                printf '%s\n' "$line"
            fi
        done < "$ASIMOV_PATH_CACHE" | sort -u | dedup_nested_paths
    } > "$ASIMOV_PATH_CACHE_TMP"
    mv -f "$ASIMOV_PATH_CACHE_TMP" "$ASIMOV_PATH_CACHE"
    ASIMOV_PATH_CACHE_TMP=""

    # Dedup the mdfind_seen file (grows with appends each run)
    if cache_readable "$ASIMOV_MDFIND_SEEN" && cache_writable "$ASIMOV_MDFIND_SEEN"; then
        sort -u "$ASIMOV_MDFIND_SEEN" > "${ASIMOV_MDFIND_SEEN}.tmp"
        mv -f "${ASIMOV_MDFIND_SEEN}.tmp" "$ASIMOV_MDFIND_SEEN"
    fi

    # Dedup the failed-state file (grows with appends each run)
    if cache_readable "$ASIMOV_FAILED_STATE" && cache_writable "$ASIMOV_FAILED_STATE"; then
        sort -u "$ASIMOV_FAILED_STATE" > "${ASIMOV_FAILED_STATE}.tmp"
        mv -f "${ASIMOV_FAILED_STATE}.tmp" "$ASIMOV_FAILED_STATE"
    fi

    if [[ "${EUID:-$(id -u)}" -eq 0 ]]; then
        local console_user
        console_user="$(stat -f '%Su' /dev/console 2>/dev/null || echo '')"
        if [[ -n "$console_user" && "$console_user" != "root" ]]; then
            chown "$console_user" "$ASIMOV_PATH_CACHE" 2>/dev/null || true
        fi
    fi
}

# Discover new dependency paths via Spotlight (mdfind) that aren't in the
# current cache. For each candidate, validate the sentinel exists in the
# parent directory. Outputs newly discovered paths to stdout.
discover_new_paths_via_mdfind() {
    local cached_paths_file="$1"

    # Pre-build active sentinel pairs (filter disabled once, not per candidate)
    local -a dir_names=() active_sentinels=()
    local pair parts dir_name seen=""
    for pair in "${ASIMOV_VENDOR_DIR_SENTINELS[@]}"; do
        local disabled=false
        if [[ ${#ASIMOV_CONFIG_DISABLED_SENTINELS[@]} -gt 0 ]]; then
            local dpair
            for dpair in "${ASIMOV_CONFIG_DISABLED_SENTINELS[@]}"; do
                [[ "$pair" == "$dpair" ]] && { disabled=true; break; }
            done
        fi
        [[ "$disabled" == true ]] && continue
        active_sentinels+=("$pair")
        read -ra parts <<< "$pair"
        dir_name="${parts[0]}"
        if [[ " $seen " != *" $dir_name "* ]]; then
            dir_names+=("$dir_name")
            seen="$seen $dir_name"
        fi
    done
    for pair in ${ASIMOV_CONFIG_EXTRA_SENTINELS[@]+"${ASIMOV_CONFIG_EXTRA_SENTINELS[@]}"}; do
        active_sentinels+=("$pair")
        read -ra parts <<< "$pair"
        dir_name="${parts[0]}"
        if [[ " $seen " != *" $dir_name "* ]]; then
            dir_names+=("$dir_name")
            seen="$seen $dir_name"
        fi
    done

    [[ ${#dir_names[@]} -eq 0 ]] && return 0

    # Build mdfind query: kMDItemContentType == "public.folder" && (name == "x" || ...)
    local name_clauses=""
    for dir_name in "${dir_names[@]}"; do
        [[ -n "$name_clauses" ]] && name_clauses="${name_clauses} || "
        name_clauses="${name_clauses}kMDItemFSName == \"${dir_name}\""
    done
    local query="kMDItemContentType == \"public.folder\" && (${name_clauses})"

    # Run mdfind, write results to temp file (avoids slow printf on 15K-line strings).
    verbose_timing "Running Spotlight query for ${#dir_names[@]} directory names…"
    local candidates_file uncached_file
    candidates_file="$(mktemp)"
    uncached_file="$(mktemp)"
    local scan_dir
    for scan_dir in "${ASIMOV_SCAN_DIRS[@]}"; do
        mdfind -onlyin "$scan_dir" "$query" 2>/dev/null >> "$candidates_file" || true
    done
    if [[ ! -s "$candidates_file" ]]; then
        rm -f "$candidates_file" "$uncached_file"
        return 0
    fi

    local total_mdfind
    total_mdfind="$(wc -l < "$candidates_file" | tr -d ' ')"
    verbose_timing "Spotlight returned ${total_mdfind} candidates"

    # Descendant filter first: skip candidates nested under cached paths. TM exclusions
    # are recursive so descendants are already covered. Run this BEFORE the exact-match
    # filter because it's fast (grep -Fvf ~4s on 15K lines) and eliminates ~90% of
    # candidates, making the subsequent exact filter much cheaper.
    if [[ -n "$cached_paths_file" && -s "$cached_paths_file" ]]; then
        local prefix_file
        prefix_file="$(mktemp)"
        sed 's|$|/|' "$cached_paths_file" > "$prefix_file"
        grep -Fvf "$prefix_file" "$candidates_file" > "$uncached_file" || true
        rm -f "$prefix_file"
    else
        cp "$candidates_file" "$uncached_file"
    fi
    rm -f "$candidates_file"

    if [[ ! -s "$uncached_file" ]]; then
        verbose_timing "All ${total_mdfind} candidates were nested under cached paths"
        rm -f "$uncached_file"
        return 0
    fi
    local uncached_count
    uncached_count="$(wc -l < "$uncached_file" | tr -d ' ')"
    verbose_timing "After descendant filter: ${uncached_count} remain (skipped $((total_mdfind - uncached_count)) nested)"

    # Exact-match filter: remove candidates already in the path cache or previously
    # checked by mdfind (no-sentinel directories that would just be rechecked for nothing).
    # Uses sort+comm for set difference — BSD grep -Fxvf is O(n×m) and takes 35s on 15K
    # lines; sort+comm is O(n log n) and handles the same in <1s.
    local combined_filter
    combined_filter="$(mktemp)"
    {
        if [[ -n "$cached_paths_file" && -s "$cached_paths_file" ]]; then cat "$cached_paths_file"; fi
        if cache_readable "$ASIMOV_MDFIND_SEEN"; then cat "$ASIMOV_MDFIND_SEEN"; fi
    } > "$combined_filter"
    if [[ -s "$combined_filter" ]]; then
        local sorted_candidates sorted_filter filtered_file
        sorted_candidates="$(mktemp)"
        sorted_filter="$(mktemp)"
        filtered_file="$(mktemp)"
        sort "$uncached_file" > "$sorted_candidates"
        sort -u "$combined_filter" > "$sorted_filter"
        comm -23 "$sorted_candidates" "$sorted_filter" > "$filtered_file"
        rm -f "$sorted_candidates" "$sorted_filter"
        mv -f "$filtered_file" "$uncached_file"
    fi
    rm -f "$combined_filter"

    if [[ ! -s "$uncached_file" ]]; then
        verbose_timing "All candidates already checked"
        rm -f "$uncached_file"
        return 0
    fi
    local filtered_count
    filtered_count="$(wc -l < "$uncached_file" | tr -d ' ')"
    verbose_timing "After cache filter: ${filtered_count} new candidates to check (skipped $((uncached_count - filtered_count)) seen)"

    if [[ ! -s "$uncached_file" ]]; then
        verbose_timing "All candidates were nested under cached paths"
        rm -f "$uncached_file"
        return 0
    fi

    local candidate mdfind_checked=0 mdfind_matched=0
    while IFS= read -r candidate; do
        [[ -d "$candidate" ]] || continue

        # Skip paths under ASIMOV_SKIP_PATHS
        local skip=false
        local skip_dir
        for skip_dir in "${ASIMOV_SKIP_PATHS[@]}"; do
            if [[ "$candidate" == "${skip_dir}"/* || "$candidate" == "${skip_dir}" ]]; then
                skip=true
                break
            fi
        done
        [[ "$skip" == true ]] && continue

        # Bash builtins instead of dirname/basename subprocesses
        local parent_dir="${candidate%/*}"
        local candidate_basename="${candidate##*/}"
        local sentinel_found=false

        # Check pre-built active sentinel pairs
        for pair in "${active_sentinels[@]}"; do
            read -ra parts <<< "$pair"
            [[ "${parts[0]}" == "$candidate_basename" ]] || continue
            local sentinel_name="${parts[1]}"
            if [[ "$sentinel_name" == *'*'* ]]; then
                # shellcheck disable=SC2086
                if (cd "$parent_dir" && ls -d $sentinel_name) >/dev/null 2>&1; then
                    sentinel_found=true
                    break
                fi
            else
                if [[ -e "${parent_dir}/${sentinel_name}" ]]; then
                    sentinel_found=true
                    break
                fi
            fi
        done

        mdfind_checked=$((mdfind_checked + 1))
        if [[ "$sentinel_found" == true ]]; then
            mdfind_matched=$((mdfind_matched + 1))
            printf '%s\n' "$candidate"
        fi
        if [[ $((mdfind_checked % 100)) -eq 0 ]]; then
            verbose_timing "  …checked ${mdfind_checked} candidates (${mdfind_matched} matched)"
        fi
    done < "$uncached_file"

    # Persist all checked candidates so they're skipped on the next cached run.
    # Prevents re-checking 1000+ no-sentinel candidates every time.
    # No-op for dry-run/no-cache (no persistent state should be written).
    if [[ -z "$ASIMOV_DRY_RUN" && -z "$ASIMOV_NO_WRITE_CACHE" ]]; then
        ensure_cache_dir
        if cache_writable "$ASIMOV_MDFIND_SEEN"; then
            cat "$uncached_file" >> "$ASIMOV_MDFIND_SEEN"
        fi
    fi
    rm -f "$uncached_file"
    verbose_timing "Spotlight: checked ${mdfind_checked} candidates, ${mdfind_matched} new matches"
}

# Paths to unconditionally skip over. This prevents Asimov from modifying the
# Time Machine exclusions for these paths (and descendants). It has an important
# side-effect of speeding up the search.
readonly ASIMOV_SKIP_PATHS=(
    "${ASIMOV_ROOT}/.Trash"
    "${ASIMOV_ROOT}/Library"
)

# A list of "directory"/"sentinel" pairs.
#
# Directories will only be excluded if the dependency ("sentinel") file exists.
#
# For example, 'node_modules package.json' means "exclude node_modules/ from the
# Time Machine backups if there is a package.json file next to it."
readonly ASIMOV_VENDOR_DIR_SENTINELS=(
    '.build Package.swift'             # Swift
    '.gradle build.gradle'             # Gradle
    '.gradle build.gradle.kts'         # Gradle Kotlin Script
    'build build.gradle'               # Gradle build files
    'build build.gradle.kts'           # Gradle Kotlin Script build files
    '.dart_tool pubspec.yaml'          # Flutter (Dart)
    '.packages pubspec.yaml'           # Pub (Dart)
    '.stack-work stack.yaml'           # Stack (Haskell)
    '.tox tox.ini'                     # Tox (Python)
    '.nox noxfile.py'                  # Nox (Python)
    '.vagrant Vagrantfile'             # Vagrant
    '.venv requirements.txt'           # virtualenv (Python)
    '.venv pyproject.toml'             # virtualenv (Python)
    'Carthage Cartfile'                # Carthage
    'Pods Podfile'                     # CocoaPods
    'DerivedData *.xcodeproj'          # Xcode DerivedData
    'bower_components bower.json'      # Bower (JavaScript)
    'build pubspec.yaml'               # Flutter (Dart)
    'build setup.py'                   # Python
    'dist setup.py'                    # PyPI Publishing (Python)
    'node_modules package.json'        # npm, Yarn (NodeJS)
    '.parcel-cache package.json'       # Parcel v2 cache (JavaScript)
    '.next package.json'               # Next.js (JavaScript)
    '.nuxt package.json'               # Nuxt (JavaScript)
    '.angular angular.json'            # Angular (JavaScript)
    '.svelte-kit svelte.config.js'     # SvelteKit (JavaScript)
    '.turbo turbo.json'                # Turborepo (JavaScript)
    '.yarn .yarnrc.yml'                # Yarn Berry cache (JavaScript)
    'cache workspace.yml'              # moonrepo task cache (.moon/cache)
    'target Cargo.toml'                # Cargo (Rust)
    'target pom.xml'                   # Maven
    'target build.sbt'                 # Sbt (Scala)
    'target plugins.sbt'               # Sbt plugins (Scala)
    'target project.clj'               # Leiningen (Clojure)
    'target deps.edn'                  # Clojure CLI
    '.cpcache deps.edn'                # Clojure CLI classpath cache
    '.shadow-cljs shadow-cljs.edn'     # Shadow-CLJS (ClojureScript)
    'bin *.csproj'                     # .NET C# build output
    'obj *.csproj'                     # .NET C# intermediate output
    'bin *.fsproj'                     # .NET F# build output
    'obj *.fsproj'                     # .NET F# intermediate output
    'vendor composer.json'             # Composer (PHP)
    'vendor Gemfile'                   # Bundler (Ruby)
    'vendor go.mod'                    # Go Modules (Golang)
    'venv requirements.txt'            # virtualenv (Python)
    'venv pyproject.toml'              # virtualenv (Python)
    '__pypackages__ pyproject.toml'    # PEP 582/PDM (Python)
    'deps mix.exs'                     # Mix dependencies (Elixir)
    '.build mix.exs'                   # Mix build files (Elixir)
    '_build mix.exs'                   # Mix build output (Elixir)
    '.terraform.d .terraformrc'        # Terraform plugin cache
    '.terragrunt-cache terragrunt.hcl' # Terragrunt
    '.terraform .terraform.lock.hcl'   # Terraform providers/modules
    '.direnv .envrc'                   # direnv
    'cdk.out cdk.json'                 # AWS CDK
    '_build dune-project'              # Dune (OCaml)
    '.zig-cache build.zig'             # Zig build cache
    'zig-out build.zig'                # Zig build output
    'elm-stuff elm.json'               # Elm packages
    '.godot project.godot'             # Godot 4 editor cache
    'renv renv.lock'                   # renv (R)
)

# A list of fixed directories to exclude from Time Machine backups.
#
# Unlike sentinel-based pairs above, these directories are always excluded
# when they exist — they represent global tool caches and artifacts that
# can be safely restored.
readonly ASIMOV_FIXED_DIRS=(
    "${ASIMOV_ROOT}/.cache"                           # XDG cache directory
    "${ASIMOV_ROOT}/.gradle/caches"                   # Gradle download cache
    "${ASIMOV_ROOT}/.gradle/wrapper"                  # Gradle wrapper distributions
    "${ASIMOV_ROOT}/.m2/repository"                   # Maven local repository
    "${ASIMOV_ROOT}/.npm/_cacache"                    # npm content-addressable cache
    "${ASIMOV_ROOT}/.nuget/packages"                  # NuGet global packages
    "${ASIMOV_ROOT}/.kube/cache"                      # Kubernetes API cache
    "${ASIMOV_ROOT}/.kube/http-cache"                 # Kubernetes HTTP cache
    "${ASIMOV_ROOT}/go/pkg/mod"                       # Go module cache (0555 inside; exclude as a whole)
)

# Record an excluded path: log for counting, compute size only with --stats.
record_excluded_path() {
    local path="$1"
    local message="$2"
    if [[ -n "$ASIMOV_STATS" ]]; then
        local rawsize size_human
        rawsize=$(du -sk "${path}" 2>/dev/null | cut -f1 || echo "0")
        echo "$rawsize" >> "$ASIMOV_SIZE_LOG"
        if [[ -z "$ASIMOV_QUIET" ]]; then
            size_human="$(format_size_kb "$rawsize")"
            printf '%s\n' "- ${message} (${size_human})."
        fi
    else
        echo "0" >> "$ASIMOV_SIZE_LOG"
        if [[ -z "$ASIMOV_QUIET" ]]; then
            printf '%s\n' "- ${message}."
        fi
    fi
}

# Process newline-separated paths from stdin: check the excluded-path cache,
# call tmutil addexclusion (unless dry-run), and log sizes.
#
# Performance notes (learned the hard way):
# - tmutil addexclusion takes ~11s per call (IPC with TM daemon). This dominates runtime.
# - Batching (tmutil addexclusion path1 path2 ...) provides NO speed benefit — tmutil
#   processes paths sequentially at ~11s each. Worse: one bad path (e.g. a read-only
#   dir in Go's module cache) fails the entire batch, wasting all accumulated time.
# - Spotlight (mdfind) can be stale: recently excluded paths may not appear in the index.
#   Without a guard, this causes re-excluding already-done paths (~11s each, wasted).
# - Three-layer defense against wasted tmutil calls:
#   1. Bulk grep against Spotlight + persistent state (instant, catches ~90%)
#   2. Filter descendants of fixed dirs (instant, catches ~5%)
#   3. tmutil isexcluded per-path guard (fast, catches remaining stale entries)
exclude_paths_from_stdin() {
    local path
    local -a all_paths=()

    # Read all paths from stdin, filtering non-directories
    while IFS=$'\n' read -r path; do
        [[ -d "$path" ]] || continue
        all_paths+=("$path")
    done
    [[ ${#all_paths[@]} -eq 0 ]] && return 0

    # Layer 1: Bulk filter against excluded-path cache (1 grep vs N subprocess spawns).
    # NEVER use per-path grep in a loop — spawning a subprocess per candidate is O(N)
    # process creation overhead that dominated runtime with ~15k mdfind candidates.
    verbose_timing "Filtering ${#all_paths[@]} paths against excluded-path cache…"
    local -a to_exclude=()
    local already_excluded=0
    if [[ -f "$ASIMOV_EXCLUDED_CACHE" ]]; then
        local new_paths_str
        new_paths_str="$(printf '%s\n' "${all_paths[@]}" | grep -Fxvf "$ASIMOV_EXCLUDED_CACHE" || true)"
        if [[ -n "$new_paths_str" ]]; then
            while IFS= read -r path; do
                to_exclude+=("$path")
            done <<< "$new_paths_str"
        fi
        already_excluded=$(( ${#all_paths[@]} - ${#to_exclude[@]} ))
        if [[ -n "$ASIMOV_VERBOSE" && $already_excluded -gt 0 ]]; then
            echo "- ${already_excluded} paths already excluded, skipping."
        fi
    else
        to_exclude=("${all_paths[@]}")
    fi
    verbose_timing "Filtered: ${#to_exclude[@]} new, ${already_excluded} already excluded"

    # Layer 2: Filter descendants of ASIMOV_FIXED_DIRS — they'll be excluded
    # unconditionally later, so calling tmutil on them individually is wasted (~11s each).
    if [[ "$ASIMOV_CONFIG_FIXED_DIRS_ENABLED" == "true" && ${#to_exclude[@]} -gt 0 ]]; then
        local -a filtered_exclude=()
        for path in "${to_exclude[@]}"; do
            local under_fixed=false
            local fixed_dir
            for fixed_dir in "${ASIMOV_FIXED_DIRS[@]}"; do
                if [[ "$path" == "${fixed_dir}/"* ]]; then
                    under_fixed=true
                    break
                fi
            done
            if [[ "$under_fixed" == false ]]; then
                filtered_exclude+=("$path")
            fi
        done
        if [[ ${#filtered_exclude[@]} -lt ${#to_exclude[@]} ]]; then
            verbose_timing "Skipped $((${#to_exclude[@]} - ${#filtered_exclude[@]})) paths inside fixed dirs"
            to_exclude=("${filtered_exclude[@]+"${filtered_exclude[@]}"}")
        fi
    fi

    [[ ${#to_exclude[@]} -eq 0 ]] && {
        verbose_timing "Nothing to exclude (${already_excluded} already excluded)"
        return 0
    }
    verbose_timing "${#to_exclude[@]} to exclude, ${already_excluded} already excluded"

    # Layer 3: tmutil isexcluded guard before the expensive addexclusion (~11s each).
    # This is the ground truth — catches paths the Spotlight cache missed (stale index,
    # interrupted previous runs, or exclusions added outside Asimov — e.g. a manually
    # excluded parent like ~/.nvm). v0.5.0 removed this check; re-adding it cut runtime
    # from 73 min to 79s on a real system with ~460 dependency paths.
    #
    # --dry-run takes this exact same path so the preview matches a real run: it still
    # runs the read-only `tmutil isexcluded` guard, but prints "Would exclude" instead
    # of calling addexclusion and never persists state.
    verbose_timing "Excluding ${#to_exclude[@]} paths via tmutil…"
    [[ -z "$ASIMOV_DRY_RUN" && -z "$ASIMOV_NO_WRITE_CACHE" ]] && ensure_cache_dir
    local tmutil_i=0 skipped_already=0
    for path in "${to_exclude[@]}"; do
        tmutil_i=$((tmutil_i + 1))
        # Ground-truth check: is this path actually already excluded?
        if tmutil isexcluded "$path" 2>/dev/null | grep -Fq '[Excluded]'; then
            skipped_already=$((skipped_already + 1))
            # Persist so we skip it via the fast cache next time (not in dry-run / no-write)
            [[ -z "$ASIMOV_DRY_RUN" && -z "$ASIMOV_NO_WRITE_CACHE" ]] && append_state "$path" "$ASIMOV_EXCLUDED_STATE"
            if [[ -n "$ASIMOV_VERBOSE" ]]; then
                echo "- ${path} is already excluded, skipping."
            fi
            continue
        fi
        if [[ -n "$ASIMOV_DRY_RUN" ]]; then
            record_excluded_path "$path" "Would exclude: ${path}"
            continue
        fi
        local path_start=$SECONDS
        # Time Machine stores an exclusion as an xattr on the item itself, so a
        # read-only directory can never be excluded — tmutil fails with
        # "Error (-20)" / EINVAL. The common case is Go's module cache, which is
        # deliberately 0555. Check first: addexclusion costs ~11s even when it fails.
        if [[ ! -w "$path" ]]; then
            echo "! ${path}: read-only, cannot be excluded — skipping." >&2
            [[ -z "$ASIMOV_NO_WRITE_CACHE" ]] && append_state "$path" "$ASIMOV_FAILED_STATE"
            continue
        fi
        # tmutil prints its POSIXError dump to stdout, not stderr — silence both.
        if ! tmutil addexclusion "${path}" >/dev/null 2>&1; then
            echo "! ${path}: failed to exclude (tmutil error), skipping." >&2
            # Persist failure so we skip this path on subsequent runs.
            # Use --no-read-cache to retry.
            [[ -z "$ASIMOV_NO_WRITE_CACHE" ]] && append_state "$path" "$ASIMOV_FAILED_STATE"
            continue
        fi
        # Persist immediately — survives Ctrl+C so the next run doesn't redo this path
        [[ -z "$ASIMOV_NO_WRITE_CACHE" ]] && append_state "$path" "$ASIMOV_EXCLUDED_STATE"
        record_excluded_path "$path" "${path} has been excluded from Time Machine backups"
        verbose_timing "  [${tmutil_i}/${#to_exclude[@]}] excluded in $((SECONDS - path_start))s: ${path}"
    done
    if [[ $skipped_already -gt 0 ]]; then
        verbose_timing "Skipped ${skipped_already} already-excluded paths (Spotlight cache was stale)"
    fi
}

# Build find parameters to skip ASIMOV_SKIP_PATHS (hardcoded directories like .Trash, Library).
# Already-excluded paths are NOT pruned here — they are filtered cheaply via grep in
# exclude_paths_from_stdin instead, avoiding the O(dirs × prune_count) performance trap.
# Result is stored in global find_parameters_skip.
build_find_skip_params() {
    find_parameters_skip=()
    local skip_dir
    for skip_dir in "${ASIMOV_SKIP_PATHS[@]}"; do
        find_parameters_skip+=( -not \( -path "${skip_dir}" -prune \) )
    done
}

# Build find parameters for all directory/sentinel pairs.
# Skips pairs disabled via config and appends extra pairs from config.
# Result is stored in global find_parameters_vendor.
build_find_vendor_params() {
    find_parameters_vendor=()
    local pair parts dir_name sentinel_name sentinel_check

    # Process built-in sentinels, skipping any disabled by config
    for pair in "${ASIMOV_VENDOR_DIR_SENTINELS[@]}"; do
        local disabled=false
        if [[ ${#ASIMOV_CONFIG_DISABLED_SENTINELS[@]} -gt 0 ]]; then
            local dpair
            for dpair in "${ASIMOV_CONFIG_DISABLED_SENTINELS[@]}"; do
                if [[ "$pair" == "$dpair" ]]; then
                    disabled=true
                    break
                fi
            done
        fi
        [[ "$disabled" == true ]] && continue

        read -ra parts <<< "${pair}"
        dir_name="${parts[0]}"
        sentinel_name="${parts[1]}"

        if [[ "$sentinel_name" == *'*'* ]]; then
            # Pass the glob pattern as a positional arg ($1), never interpolated into
            # the sh -c script body, so a malicious sentinel can't inject shell commands.
            # $1 is intentionally unquoted so the inner sh glob-expands the pattern; its
            # value is never re-parsed as shell code, so injection is not possible.
            # shellcheck disable=SC2016,SC2086
            sentinel_check=( -execdir sh -c 'ls -d -- $1 >/dev/null 2>&1' _ "${sentinel_name}" \; )
        else
            sentinel_check=( -execdir test -e "${sentinel_name}" \; )
        fi

        find_parameters_vendor+=( -or \( \
            -type d \
            -name "${dir_name}" \
            "${sentinel_check[@]}" \
            -prune \
            -print \
        \) )
    done

    # Append extra sentinels from config
    for pair in ${ASIMOV_CONFIG_EXTRA_SENTINELS[@]+"${ASIMOV_CONFIG_EXTRA_SENTINELS[@]}"}; do
        read -ra parts <<< "${pair}"
        dir_name="${parts[0]}"
        sentinel_name="${parts[1]}"

        if [[ "$sentinel_name" == *'*'* ]]; then
            # sentinel_name here comes from the user's config; pass it as a positional
            # arg ($1) instead of interpolating it into the sh -c script body to
            # prevent shell command injection from a crafted config value. $1 is
            # intentionally unquoted so the inner sh glob-expands it; its value is never
            # re-parsed as shell code, so a payload like "*.x'; cmd; '" can't execute.
            # shellcheck disable=SC2016,SC2086
            sentinel_check=( -execdir sh -c 'ls -d -- $1 >/dev/null 2>&1' _ "${sentinel_name}" \; )
        else
            sentinel_check=( -execdir test -e "${sentinel_name}" \; )
        fi

        find_parameters_vendor+=( -or \( \
            -type d \
            -name "${dir_name}" \
            "${sentinel_check[@]}" \
            -prune \
            -print \
        \) )
    done
}

# Format a size in KB as human-readable string (e.g. 1.2G, 500M, 42K).
format_size_kb() {
    local kb="$1"
    if [[ "$kb" -ge ASIMOV_KB_PER_GB ]]; then
        local whole=$((kb / ASIMOV_KB_PER_GB))
        local frac=$(( (kb % ASIMOV_KB_PER_GB) * 10 / ASIMOV_KB_PER_GB ))
        printf '%s.%sG' "$whole" "$frac"
    elif [[ "$kb" -ge ASIMOV_KB_PER_MB ]]; then
        local whole=$((kb / ASIMOV_KB_PER_MB))
        local frac=$(( (kb % ASIMOV_KB_PER_MB) * 10 / ASIMOV_KB_PER_MB ))
        printf '%s.%sM' "$whole" "$frac"
    else
        printf '%sK' "$kb"
    fi
}

# Print summary of excluded (or would-exclude) count, and total size when --stats is set.
print_exclusion_summary() {
    local excluded_count msg
    excluded_count=$(wc -l < "$ASIMOV_SIZE_LOG" | tr -d ' ')

    if [[ "$excluded_count" -eq 0 ]]; then
        if [[ -n "$ASIMOV_DRY_RUN" ]]; then
            msg="No directories would be excluded."
        else
            msg="✓ Done! No new directories to exclude."
        fi
    else
        local verb
        if [[ -n "$ASIMOV_DRY_RUN" ]]; then
            verb="Would exclude"
        else
            verb="✓ Done! Excluded"
        fi
        if [[ -n "$ASIMOV_STATS" ]]; then
            local total_kb total_human
            total_kb=$(awk '{s+=$1} END {print s}' "$ASIMOV_SIZE_LOG")
            total_human="$(format_size_kb "$total_kb")"
            msg="${verb} ${excluded_count} directories, totalling ${total_human}."
        else
            msg="${verb} ${excluded_count} directories."
        fi
    fi

    printf '\n%s%s%s\n' "$ASIMOV_COLOR_SUCCESS" "$msg" "$ASIMOV_COLOR_RESET"
}

# --- Main: build find params, run find (or use cache), process paths, then fixed dirs, then summary ---

if [[ ! -d "$ASIMOV_ROOT" ]]; then
    echo "asimov: root directory does not exist or is not a directory: $ASIMOV_ROOT" >&2
    exit 1
fi

# Determine whether to use the cache or do a full scan.
# Cache is read when the cache file exists and reads aren't disabled
# (--no-read-cache / --full-scan / --no-cache force a full scan).
use_cache=false
if [[ -z "$ASIMOV_NO_READ_CACHE" ]] && cache_readable "$ASIMOV_PATH_CACHE"; then
    use_cache=true
fi

if [[ "$use_cache" == true ]]; then
    # --- Cached run ---
    [[ -z "$ASIMOV_QUIET" ]] && printf '\n%s⏳ Using cached paths…%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"

    # Read cache, filter stale/out-of-scope paths, collect valid ones
    cached_valid="$(mktemp)"
    read_path_cache > "$cached_valid"
    verbose_timing "Cache read: $(wc -l < "$cached_valid" | tr -d ' ') valid paths"

    # Incremental discovery via Spotlight
    [[ -z "$ASIMOV_QUIET" ]] && printf '%s🔍 Checking for new projects via Spotlight…%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"
    new_paths="$(mktemp)"
    discover_new_paths_via_mdfind "$cached_valid" > "$new_paths"
    verbose_timing "Spotlight discovery: $(wc -l < "$new_paths" | tr -d ' ') new paths"

    # Exclude all paths (cached + new), deduped to remove nested redundancies.
    # Time Machine exclusions are recursive, so excluding a parent covers descendants.
    [[ -z "$ASIMOV_QUIET" ]] && printf '%s📦 Processing matches…%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"
    deduped="$(mktemp)"
    { cat "$cached_valid"; cat "$new_paths"; } | sort -u | dedup_nested_paths > "$deduped"
    total_before=$(( $(wc -l < "$cached_valid" | tr -d ' ') + $(wc -l < "$new_paths" | tr -d ' ') ))
    total_after=$(wc -l < "$deduped" | tr -d ' ')
    verbose_timing "Dedup: ${total_before} paths → ${total_after} (removed $((total_before - total_after)) nested)"
    cat "$deduped" | exclude_paths_from_stdin
    rm -f "$deduped"

    # Update cache: append new discoveries to existing cache, then sort/dedup/prune
    while IFS= read -r path; do
        append_path_to_cache "$path"
    done < "$new_paths"
    finalize_path_cache
    verbose_timing "Cache finalized"

    rm -f "$cached_valid" "$new_paths"
else
    # --- Full scan ---
    [[ -z "$ASIMOV_QUIET" ]] && printf '\n%s⏳ Scanning for dependency directories…%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"

    build_find_skip_params
    build_find_vendor_params
    verbose_timing "Find parameters built"

    [[ -z "$ASIMOV_QUIET" ]] && printf '%s📦 Processing matches…%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"

    # Stream find output: tee writes to cache incrementally, pipe feeds exclusion.
    # On interrupt, tee has already appended every path find emitted, so the
    # next run can use the partial cache.
    verbose_timing "Starting find traversal of ${ASIMOV_SCAN_DIRS[*]}…"
    # The tee'd branch is only safe when the cache is actually writable: a failing
    # tee takes the whole pipeline down under pipefail. Fall back to the plain
    # pipeline otherwise, so an unusable cache costs speed, not the run (#122).
    if [[ -z "$ASIMOV_DRY_RUN" && -z "$ASIMOV_NO_WRITE_CACHE" ]] \
        && { ensure_cache_dir; cache_writable "$ASIMOV_PATH_CACHE"; }; then
        init_path_cache
        { find "${ASIMOV_SCAN_DIRS[@]}" \( "${find_parameters_skip[@]}" \) \( -false "${find_parameters_vendor[@]}" \) \
            || true; } | tee -a "$ASIMOV_PATH_CACHE" | exclude_paths_from_stdin
        verbose_timing "Find + exclude complete"
        finalize_path_cache
        verbose_timing "Cache finalized"
    else
        { find "${ASIMOV_SCAN_DIRS[@]}" \( "${find_parameters_skip[@]}" \) \( -false "${find_parameters_vendor[@]}" \) \
            || true; } | exclude_paths_from_stdin
        verbose_timing "Find + exclude complete"
    fi
fi

# Exclude built-in fixed dirs only when enabled via config.
if [[ "$ASIMOV_CONFIG_FIXED_DIRS_ENABLED" == "true" ]]; then
    [[ -z "$ASIMOV_QUIET" ]] && printf '\n%s💾 Excluding known cache directories…%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"
    for fixed_dir in "${ASIMOV_FIXED_DIRS[@]}"; do
        if [[ -d "$fixed_dir" ]]; then
            echo "$fixed_dir"
        fi
    done | exclude_paths_from_stdin
fi

# Always process extra fixed dirs from config (user explicitly wants them).
if [[ ${#ASIMOV_CONFIG_EXTRA_FIXED_DIRS[@]} -gt 0 ]]; then
    [[ -z "$ASIMOV_QUIET" ]] && printf '\n%s⚙️  Excluding user-configured directories…%s\n' \
        "$ASIMOV_COLOR_INFO" "$ASIMOV_COLOR_RESET"
    for fixed_dir in "${ASIMOV_CONFIG_EXTRA_FIXED_DIRS[@]}"; do
        if [[ -d "$fixed_dir" ]]; then
            echo "$fixed_dir"
        fi
    done | exclude_paths_from_stdin
fi

verbose_timing "All exclusions processed"
[[ -z "$ASIMOV_QUIET" ]] && print_exclusion_summary
exit 0