fix: skip read-only dirs and stop tmutil's POSIXError leaking into output

Go's module cache is deliberately 0555. A Time Machine exclusion is stored as
an xattr on the item itself, so a read-only directory can never take one —
tmutil fails with "Error (-20)" / EINVAL(22) after burning ~11s per call.

The failures were long attributed to the '@' in Go module version paths. That
was wrong: a writable path containing '@' excludes fine; permissions were
always the cause. Comments corrected and both cases now have regression tests.

- Pre-check writability and skip with an accurate message, before the ~11s call
- Silence tmutil's stdout too: it prints its POSIXError dump to stdout, not
  stderr, so the existing 2>/dev/null never suppressed it
- Add ~/go/pkg/mod to ASIMOV_FIXED_DIRS — excludes the cache in one call and
  lets the existing Layer 2 filter drop every vendor/ dir beneath it
- Mock tmutil now mirrors the real stream split (dump on stdout, error on
  stderr) so the suite can actually catch this class of leak
- README: split Install into Stable / Beta / Quick start; refresh Credits for
  the handover; document the Go cache and custom-GOPATH config

Author: django23

CHANGELOG.md

@@ -8,10 +8,16 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- Go's module cache (`~/go/pkg/mod`) is now one of the built-in global caches (opt-in via `[fixed_dirs] enabled = true`). Excluding the cache root covers every dependency inside it in a single `tmutil` call, instead of attempting each `vendor/` directory individually (~11s apiece, and doomed — see below). Using a custom `GOPATH`? Add it with `[fixed_dirs] extra`
+
 ### Changed
 
 ### Fixed
 
+- Read-only directories are now detected and skipped up front with a clear `read-only, cannot be excluded` message, instead of burning ~11s on a `tmutil addexclusion` call that can never succeed. A Time Machine exclusion is stored as an extended attribute **on the item itself**, so a `0555` directory can never take one — Go's module cache is deliberately read-only, which is why its `vendor/` directories always failed
+- `tmutil`'s `POSIXError(_nsError: …Code=22 "Invalid argument")` dump no longer leaks into Asimov's output. `tmutil` prints it to **stdout** (not stderr), so the existing `2>/dev/null` never suppressed it; both streams are now silenced and Asimov prints its own warning instead
+- Corrected a long-standing misdiagnosis in the code comments: these failures were attributed to the `@` in Go module version paths. `@` is irrelevant — a writable path containing `@` excludes fine. Read-only permissions were always the cause (regression tests now cover both)
+
 ### Removed
 
 ## [0.9.0] — 2026-07-09

README.md

@@ -15,14 +15,36 @@ Asimov scans your home directory, finds dependency folders next to their config
 
 ## Install
 
-> **Beta:** `v0.9.0` is in pre-release testing. Install it with the curl command below.
+### Stable — v0.8.0
+
+```sh
+brew install django23/tap/asimov
+brew services start django23/tap/asimov
+```
+
+> `brew install asimov` from homebrew-core is still **v0.3.0** and unmaintained. Use the tap above.
+
+### Beta — v0.9.0-beta.1
+
+Currently in testing, and where the newest ecosystems and the ~1–2s cached runs live:
 
 ```sh
 curl -fsSL https://raw.githubusercontent.com/AsimovMac/asimov/v0.9.0-beta.1/scripts/install-remote.sh \
   | ASIMOV_REF=v0.9.0-beta.1 bash
 ```
 
-That's it — Asimov installs to `~/.local/bin` and runs at midday, every day. See [other install methods](#other-install-methods) for Homebrew and source installs.
+Installs to `~/.local/bin`. Feedback and bug reports very welcome — [open an issue](https://github.com/AsimovMac/asimov/issues).
+
+### Quick start
+
+```sh
+asimov --dry-run    # preview what would be excluded — changes nothing
+asimov              # apply
+```
+
+That's it. Asimov then runs itself once a day, every day. Add `--stats` to either command to see sizes and how much space you're saving.
+
+See [other install methods](#other-install-methods) to build from source.
 
 ## What you'll see
 
@@ -79,7 +101,7 @@ This means Asimov never touches a folder that just happens to share a common nam
 | **R**                       | `renv`                                                                                                                           |
 | **DevOps / IaC**            | `.terraform`, `.terragrunt-cache`, `.vagrant`, `.direnv`, `cdk.out`                                                              |
 | **Game dev**                | `.godot`                                                                                                                         |
-| **Global caches** (opt-in)  | `~/.cache`, `~/.gradle/caches`, `~/.m2/repository`, `~/.npm/_cacache`, `~/.nuget/packages`, `~/.kube/cache`                      |
+| **Global caches** (opt-in)  | `~/.cache`, `~/.gradle/caches`, `~/.m2/repository`, `~/.npm/_cacache`, `~/.nuget/packages`, `~/.kube/cache`, `~/go/pkg/mod`         |
 
 **Don't see your tool?** You can teach Asimov your own directory + sentinel pairs in a couple of lines — no need to wait for a release. See [Add your own patterns](#add-your-own-patterns).
 
@@ -146,17 +168,11 @@ Global tool caches in your home directory (`~/.cache`, `~/.gradle/caches`, …)
 [fixed_dirs]
 enabled = true                   # exclude the built-in global caches
 extra   = ~/my-build-cache       # plus any paths you name (always excluded when they exist)
+extra   = ~/golang/pkg/mod       # e.g. a Go module cache under a custom GOPATH
 ```
 
 ## Other install methods
 
-**Homebrew** — the tap currently tracks the last stable (`0.8.0`), not the `0.9.0` beta:
-
-```sh
-brew install django23/tap/asimov
-brew services start django23/tap/asimov
-```
-
 **From source:**
 
 ```sh
@@ -179,7 +195,11 @@ See [UPGRADING.md](UPGRADING.md) for migrating from v0.4.x or the original `stev
 
 ## Credits
 
-Asimov was created by [Steve Grunwell](https://github.com/stevegrunwell) and maintained at [`stevegrunwell/asimov`](https://github.com/stevegrunwell/asimov) through v0.3.0. Versions since `0.4.0` add performance improvements, config-file support, and expanded ecosystem coverage.
+Asimov was created by **[Steve Grunwell](https://github.com/stevegrunwell)**, who built and maintained it at `stevegrunwell/asimov` from 2018 through v0.3.0 — the version most people know it by. Thank you, Steve, for the years of work and for [handing it on](https://github.com/AsimovMac/asimov/issues/99) so carefully.
+
+The project now lives at [`AsimovMac/asimov`](https://github.com/AsimovMac/asimov) (the original repo, transferred — the old URL still redirects here), maintained by [@django23](https://github.com/django23). Releases from `v0.4.0` onward add expanded ecosystem coverage, a config file, and the caching that took typical runs from ~75s to ~1–2s.
+
+Built on the contributions of everyone who filed issues and PRs over the years. Asimov is, and stays, MIT-licensed and community-driven.
 
 ## Contributing
 

asimov

@@ -175,7 +175,7 @@ mdfind -onlyin "${ASIMOV_SCAN_DIR}" "com_apple_backup_excludeItem = 'com.apple.b
     | sort -u > "$ASIMOV_EXCLUDED_CACHE" || true
 spotlight_count="$(wc -l < "$ASIMOV_EXCLUDED_CACHE" | tr -d ' ')"
 # Merge persistent excluded + failed state into the Spotlight cache.
-# Failed paths (e.g. Go modules with @ chars) are included so the bulk filter
+# 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.
@@ -620,6 +620,7 @@ readonly ASIMOV_FIXED_DIRS=(
     "${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.
@@ -648,8 +649,8 @@ record_excluded_path() {
 # 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. Go modules with
-#   @ characters) fails the entire batch, wasting all accumulated time before fallback.
+#   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:
@@ -748,10 +749,20 @@ exclude_paths_from_stdin() {
             continue
         fi
         local path_start=$SECONDS
-        if ! tmutil addexclusion "${path}" 2>/dev/null; then
+        # 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" ]] && printf '%s\n' "$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.
-            # Common cause: Go module paths with @ characters. Use --no-read-cache to retry.
+            # Use --no-read-cache to retry.
             [[ -z "$ASIMOV_NO_WRITE_CACHE" ]] && printf '%s\n' "$path" >> "$ASIMOV_FAILED_STATE"
             continue
         fi

tests/behavior.bats

@@ -233,6 +233,28 @@ enabled = true"
   [[ "$(count_exclusions)" -eq 3 ]]
 }
 
+@test "excludes the Go module cache when fixed dirs are enabled" {
+  mkdir -p "${HOME}/go/pkg/mod"
+  write_config "[fixed_dirs]
+enabled = true"
+  run_asimov
+  assert_excluded "${HOME}/go/pkg/mod"
+}
+
+@test "excludes the Go module cache as a whole, not each vendor dir inside it" {
+  # Real-world shape: the module cache holds many read-only vendor/ dirs behind
+  # @-versioned paths. Excluding the cache root covers all of them in one call;
+  # excluding each individually would be ~11s apiece and fail on the 0555 perms.
+  create_project "go/pkg/mod/github.com/foo/bar@v1.2.3" "go.mod" "vendor"
+  write_config "[fixed_dirs]
+enabled = true"
+
+  run_asimov
+
+  assert_excluded "${HOME}/go/pkg/mod"
+  refute_excluded "${HOME}/go/pkg/mod/github.com/foo/bar@v1.2.3/vendor"
+}
+
 @test "does not re-exclude already excluded fixed directory" {
   mkdir -p "${HOME}/.cache"
   write_config "[fixed_dirs]
@@ -407,6 +429,62 @@ extra = .custom-deps *.x'; touch ${pwned}; '"
   [[ "$(count_exclusions)" -eq 0 ]]
 }
 
+@test "does not leak tmutil's POSIXError dump into output" {
+  create_project "Code/Bad-Project" "package.json" "node_modules"
+
+  ASIMOV_TEST_TMUTIL_FAIL_PATHS="${TEST_TEMP_DIR}/.tmutil_fail_paths"
+  export ASIMOV_TEST_TMUTIL_FAIL_PATHS
+  echo "${HOME}/Code/Bad-Project/node_modules" > "$ASIMOV_TEST_TMUTIL_FAIL_PATHS"
+
+  run_asimov
+
+  [[ "$status" -eq 0 ]]
+  # tmutil dumps POSIXError(...) to stdout — not stderr — so a bare 2>/dev/null
+  # lets it leak. Asimov must swallow it and print its own warning instead.
+  [[ "$output" != *"POSIXError"* ]]
+  [[ "$output" == *"failed to exclude"* ]]
+}
+
+# =============================================================================
+# Read-only directories (e.g. Go's module cache, which is 0555)
+# =============================================================================
+
+@test "skips read-only directory without attempting tmutil" {
+  create_project "Code/Go-Project" "go.mod" "vendor"
+  chmod 555 "${HOME}/Code/Go-Project/vendor"
+
+  run_asimov
+  local status_copy="$status" output_copy="$output"
+  chmod 755 "${HOME}/Code/Go-Project/vendor"
+
+  [[ "$status_copy" -eq 0 ]]
+  refute_excluded "${HOME}/Code/Go-Project/vendor"
+  # The read-only pre-check should fire — NOT the tmutil-failure path. A Time
+  # Machine exclusion is an xattr on the item, so a 0555 dir can never take one.
+  [[ "$output_copy" == *"read-only"* ]]
+  [[ "$output_copy" != *"tmutil error"* ]]
+}
+
+@test "read-only directory is recorded in failed state" {
+  create_project "Code/Go-Project" "go.mod" "vendor"
+  chmod 555 "${HOME}/Code/Go-Project/vendor"
+
+  run_asimov
+  chmod 755 "${HOME}/Code/Go-Project/vendor"
+
+  assert_failed "${HOME}/Code/Go-Project/vendor"
+}
+
+@test "writable directory containing @ is excluded (@ is not the blocker)" {
+  # Regression guard: the failure on Go module paths was long attributed to the
+  # '@' in the version syntax. It is not — read-only permissions are the cause.
+  create_project "Code/cheat@v0.0.0-20211009161301" "go.mod" "vendor"
+
+  run_asimov
+
+  assert_excluded "${HOME}/Code/cheat@v0.0.0-20211009161301/vendor"
+}
+
 # =============================================================================
 # --help, --version, unknown option
 # =============================================================================

tests/bin/tmutil

@@ -45,8 +45,12 @@ case "$subcommand" in
       # Simulate failure for paths listed in ASIMOV_TEST_TMUTIL_FAIL_PATHS
       if [[ -n "${ASIMOV_TEST_TMUTIL_FAIL_PATHS:-}" && -f "${ASIMOV_TEST_TMUTIL_FAIL_PATHS}" ]]; then
         if grep -Fxq "$path" "$ASIMOV_TEST_TMUTIL_FAIL_PATHS" 2>/dev/null; then
-          echo "Error (-50) while attempting to change exclusion setting." >&2
-          exit 1
+          # Mirror real tmutil: the POSIXError dump goes to STDOUT (not stderr),
+          # while the "Error (-NN)" line goes to stderr. Keeping both faithful is
+          # what lets tests catch the dump leaking into Asimov's output.
+          echo 'POSIXError(_nsError: Error Domain=NSPOSIXErrorDomain Code=22 "Invalid argument")'
+          echo "${path}: Error (-50) while attempting to change exclusion setting." >&2
+          exit 22
         fi
       fi
       # Idempotent: don't add if already present (matches real tmutil)