---
name: xtask-gen-deadlocks-under-cargo-run
description: "`cargo run -p xtask -- gen` DEADLOCKS — xtask shells out to `cargo build -p spt` while the outer cargo still holds the target lock; run target/debug/xtask.exe directly"
metadata: 
  node_type: memory
  type: reference
  originSessionId: f635b37f-9074-4de1-9540-eb96bcd49e42
  modified: 2026-08-04T23:54:32.885Z
---

`cargo run -p xtask -- gen` (the docs-drift regen) can hang **forever** with no error.
`gen` calls `spt_bin()`, which shells out to `cargo build -q -p spt --bin spt`; that inner
cargo blocks on the target-directory lock the OUTER `cargo run` is still holding. The
symptom is silent: xtask.exe is built, then a second `cargo` and an `rustc` sit at ~0.05s
CPU for as long as you let them. Measured 2026-08-04 in `.worktrees/w1t2-perch-gc`: 40
minutes of nothing, diagnosed only by `Get-Process cargo,rustc | Select StartTime,CPU`.

**How to apply:** run the built binary — `./target/debug/xtask.exe gen` (or `check`) — never
`cargo run -p xtask -- gen`. Same rule the pool-claim path already follows for a different
reason ([[lane-check-via-main-pool-prebuilt-xtask]]). If xtask.exe does not exist yet,
`cargo build -p xtask` FIRST as its own command, then invoke the exe. A wedged pair is safe
to `Stop-Process`; cargo re-acquires the lock cleanly afterwards.

Diagnostic that separates "slow cold build" from "wedged": a compiling rustc burns CPU, a
blocked one does not. Check CPU, not elapsed time. Kin [[cli-command-docs-drift]],
[[clap-doc-comment-leaks-req-tag]].