Optimize Rust builds across worktrees

Author: Pyiner

.cargo/config.toml

@@ -0,0 +1,13 @@
+[build]
+rustc-wrapper = "scripts/sccache-rustc-wrapper.sh"
+incremental = false
+
+[profile.dev]
+debug = "line-tables-only"
+
+[profile.test]
+debug = "line-tables-only"
+
+[env]
+SCCACHE_CACHE_SIZE = { value = "20G", force = false }
+SCCACHE_IGNORE_SERVER_IO_ERROR = { value = "1", force = false }

AGENTS.md

@@ -141,6 +141,11 @@ Detailed runtime and SDK rules:
 Use the narrowest reliable validation for the touched area. Common commands and
 fallbacks live in @docs/agents/validation.md.
 
+Keep a separate Cargo `target` directory in every concurrent Rust worktree.
+The checked-in `.cargo/config.toml` disables incremental/full dev-test debug
+artifacts and uses the worktree-aware sccache wrapper; do not replace it with a
+single shared `CARGO_TARGET_DIR`.
+
 For Rust changes, prefer the fast local loop before any full workspace run:
 `scripts/test/rust_tier1_fast.sh --changed`. For focused work, run the touched
 crate or exact test directly, for example `cargo test -p garyx-gateway --lib`,

CLAUDE.md

@@ -141,6 +141,11 @@ Detailed runtime and SDK rules:
 Use the narrowest reliable validation for the touched area. Common commands and
 fallbacks live in @docs/agents/validation.md.
 
+Keep a separate Cargo `target` directory in every concurrent Rust worktree.
+The checked-in `.cargo/config.toml` disables incremental/full dev-test debug
+artifacts and uses the worktree-aware sccache wrapper; do not replace it with a
+single shared `CARGO_TARGET_DIR`.
+
 For Rust changes, prefer the fast local loop before any full workspace run:
 `scripts/test/rust_tier1_fast.sh --changed`. For focused work, run the touched
 crate or exact test directly, for example `cargo test -p garyx-gateway --lib`,

docs/agents/validation.md

@@ -54,3 +54,22 @@ cargo test -p garyx-gateway --lib
 cargo test -p garyx-router --all-targets
 cargo test -p garyx-channels --lib
 ```
+
+## Rust Worktree Cache
+
+Garyx disables Cargo incremental output and full debugger symbols for dev/test
+profiles, then uses `scripts/sccache-rustc-wrapper.sh` to share compiler output
+across concurrent Git worktrees. The wrapper normalizes the current checkout
+root before invoking `sccache`; if `sccache` is unavailable it invokes `rustc`
+directly, so CI and fresh machines keep working.
+
+Install the local cache on macOS and inspect its effectiveness with:
+
+```bash
+brew install sccache
+sccache --show-stats
+```
+
+The repository config caps the local cache at 20 GiB. Keep each active
+worktree's own `target` directory so Cargo builds do not serialize on one build
+directory, and remove the whole worktree after its task is approved.

scripts/sccache-rustc-wrapper.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -eq 0 ]]; then
+  echo "usage: sccache-rustc-wrapper.sh <rustc> [args...]" >&2
+  exit 2
+fi
+
+if [[ -n "${SCCACHE_BIN:-}" ]]; then
+  sccache_bin="$SCCACHE_BIN"
+elif sccache_bin="$(command -v sccache 2>/dev/null)" && [[ -n "$sccache_bin" ]]; then
+  :
+else
+  exec "$@"
+fi
+
+manifest_dir="${CARGO_MANIFEST_DIR:-$PWD}"
+candidate="$manifest_dir"
+while [[ "$candidate" != "/" && -n "$candidate" ]]; do
+  if [[ -e "$candidate/.git" ]]; then
+    case ":${SCCACHE_BASEDIRS:-}:" in
+      *":$candidate:"*) ;;
+      *) export SCCACHE_BASEDIRS="$candidate${SCCACHE_BASEDIRS:+:$SCCACHE_BASEDIRS}" ;;
+    esac
+    break
+  fi
+  candidate="${candidate%/*}"
+  [[ -n "$candidate" ]] || candidate="/"
+done
+
+if [[ "${GARYX_SCCACHE_PRINT_CONFIG:-0}" == "1" ]]; then
+  echo "SCCACHE_BIN=$sccache_bin"
+  echo "SCCACHE_BASEDIRS=${SCCACHE_BASEDIRS:-}"
+  exit 0
+fi
+
+exec "$sccache_bin" "$@"