Repository navigation
fix(worktrees): cover WSL distro history and bound the retirement backfill scan (STA-4472, STA-4473) - #14924
Conversation
7dd1413 to
6ee943d
Compare
efeec37 to
7287583
Compare
|
BEFORE — With distro-local agent-history discovery disabled, the create-worktree composer still proposes Local screenshot (upload blocked; AFTER — With the distro's agent-history directory included as a discovery source, Local screenshot (upload blocked): Notes: |
Visual proof — real Windows host, real WSL distro (Ubuntu-24.04)Captured through Playwright CDP against an isolated dev Orca instance (own dev user-data path, own Setup: an agent conversation bucket for the working directory BEFORE — distro-local history excluded from discovery (the STA-4472 defect). The composer still AFTER — with this PR, the distro's agent-history directory is a discovery source. Non-visual validation on the same host
|
4842f2d to
4549697
Compare
Review loop complete — 14 rounds, 13 fix commitsTwo consecutive final rounds reported no correctness bug, and the last one independently What the rounds found and fixedThe original commit's bound was a deadline plus a 60s failure backoff. That paces retries but does
One change was reverted: tracing a WSL repo's Windows-side workspaces through the drvfs mirror. Platform validation — real Windows host, real WSL distro (Ubuntu-24.04)
Evidence qualityWhole-file production revert is not a usable instrument here — reverting deletes the extracted Residual risk — accepted, not fixed
StackingI agree with the earlier recommendation to land this before #14919 rather than after. The two |
…kfill scan (STA-4472, STA-4473)
…ust their rate The scan deadline abandons a listing, it cannot cancel one: an unabortable readdir keeps its libuv threadpool thread until the OS releases it. The failure backoff paced retries but never counted the abandoned calls, so a mount that stayed wedged stacked a new stuck thread on every lapse until the four-thread pool starved every other filesystem user in the process. UNC reads were already bounded by the WSL gate's permit accounting; plain SMB/NFS listings were not. Cap the outstanding listings process-wide and serve the memoized failure once the cap is reached. Recovery is preserved: a slot frees as soon as an abandoned listing settles.
…nalising healthy repos Three review findings on the scan bound: - A listing that landed after the 15s deadline had its result discarded. Under the WSL gate that is the common case, not an edge one: the gate admits a single scan at a time and allows it 60s, four times this deadline. The namespace was then left unseeded on exactly the mounts this feature exists to cover. The answer is now kept when it arrives. - A namespace deferred at the outstanding-listing cap never touched the wedged mount, so arming its backoff spread one bad mount's outage to repos on healthy disks. Deferrals no longer memoize; the next create retries as soon as a slot frees. - The cap comment claimed it bounds threadpool starvation. It bounds this module's share only; the WSL gate and its close lane hold threads of their own. Comment corrected. Also stub the WSL resolver in the UNC-root unit test, which otherwise shells out to wsl.exe and boots the developer's distro on a Windows runner.
…ackoff on a monotonic clock
Two more review findings on the outstanding-listing cap:
- The cap counted every in-flight listing, not just the stuck ones, so it fired on healthy
machines. Nested workspaces give each repo its own scan key, so a few first-time backfills are
routinely in flight together; the third was rejected and its create then picked a name against
an unseeded registry. Only listings that have outlived their deadline occupy a slot now, which
is what the cap was always meant to bound — healthy scans finish in milliseconds.
- The backoff fence compared wall-clock times. The WSL gate this scan runs under deliberately
avoids wall time for exactly this ('would misjudge stuckness across laptop sleep or NTP steps');
a backward step pinned a namespace in its failure memo for the size of the step. Now monotonic.
A third finding — that a late listing writing into an entry a retry has replaced loses the answer —
was investigated and refuted. An entry is only ever read back through the map, and callers hold the
promise rather than the entry, so a write to a replaced entry cannot be observed. No guard added:
the test for it passed with and without one.
…tial answer usable Replaces the process-wide listing budget with a per-namespace rule, and stops a refused source throwing away the sources that did read. - A global budget was the wrong shape: one wedged mount spends it on its own retries (lapse, restack, lapse) and then every other namespace — including repos on healthy local disks — is refused for the process lifetime, which is a strictly larger blast radius than the wedge it replaced. A namespace now simply may not start a second listing while its own is still stuck, so a bad mount costs exactly one thread and nothing else is affected. - Rethrowing a gate refusal abandoned the whole scan at the first source. For a WSL repo the UNC workspace root is listed first, so a stuck 9P route also discarded the plain, readable Windows-side bucket scan that needs no distro access — worse than the behaviour before the split. Discovery now returns what it read plus a "complete" flag; the names are used, and only the memoization is withheld so the hole is retried. - An I/O failure was reported as a complete empty listing, so a transient EIO on a redirected or network home memoized "nothing is retired" for the process lifetime. Only ENOENT/ENOTDIR now count as a complete answer. The recovery tests now release the stalled listing rather than leaving it pending forever: a retry while the previous call is still stuck is precisely what stacks threads.
…ot resolve Resolving a distro home shells out to wsl.exe, which returns nothing for a stopped or slow distro (the call has a 5s timeout) or when wsl.exe is not resolvable from the Electron process. That case dropped the distro bucket source silently and still reported the scan complete, so the empty answer was memoized for the whole process lifetime. That is the STA-4472 defect re-entering through the back door: the distro is exactly where a WSL workspace's agent history lives, so a workspace whose directory is gone leaves its only surviving evidence unread, and the next generated create reissues that cwd. It does not self-heal either — the scan key is derived from the probe path, which is unchanged by a failed home resolution. An unresolved distro now marks the scan incomplete, which serves the names that were found while leaving the hole to be retried after the backoff.
…istro too Distro discovery keyed only on the workspace root being a UNC path, but a WSL repo can legitimately own workspaces under C:\. computeWorkspaceRootAsync mirrors the workspace dir into the distro only when the distro home resolves at create time; when that wsl.exe call fails it falls back to the drive path, and those workspaces stay on the Windows side. The agent is still spawned through wsl.exe, so its cwd is the drvfs mirror (/mnt/c/...) and its bucket lands in the distro's own ~/.claude/projects, where the host-home scan cannot see it. The scan then reported complete and memoized the empty answer, so the name was reissued and the next occupant inherited the previous conversation — the STA-4472 defect, in the one configuration the UNC check does not cover. Which distro to look in comes from the repo path rather than the workspace root, since that is what still identifies the distro once the root is a drive path.
…ation Reverts the previous commit. The drvfs branch traced a WSL repo's Windows-side workspaces into the distro, but its production wiring cannot be pinned: the distro comes from parseWslPath(repo.path), which short-circuits off win32, so no assertion on a Linux or macOS runner can reach it — deleting the wiring line left every test green. Shipping an unpinnable branch is the exact unreached-module shape this PR exists to close, and it is not worth it here: the branch only pays off in a narrow race where getWslHomeAsync fails while the workspace root is computed and then succeeds seconds later during discovery. Whenever the distro home resolves, the root is UNC and the existing path already covers it; whenever it does not, the scan is already reported incomplete and retried. Also adds the missing guard on the other side of the same classification: ENOENT and ENOTDIR mean "no agent state on this machine", which is a complete answer. That is the common case for a fresh or Codex-only install, and misclassifying it as incomplete would turn the one-time seed into a 60s-interval rescan for the life of the process. The expression had no test; it does now.
The test that claimed to cover it settled the stalled listing and re-entered in the same tick, so outstanding cleared only in a later microtask and the no-restack rule answered first. It was a duplicate of the test above it, and the backoff clause it was meant to pin had no coverage at all: deleting the clause left all twelve tests in both files green, so a regression that re-probes a wedged mount on every generated create would have shipped. Flush the microtask so the listing is genuinely settled, then assert both directions — the memo still serves the failure inside the window, and the same call succeeds once the window lapses.
… distro looks like Windows reports an unreachable 9P route as ENOENT, so a distro that has merely been shut down is indistinguishable from one that never held any buckets. wsl.ts already refuses to trust a UNC ENOENT for the same reason, probing inside the distro instead. The classification added earlier called ENOENT a complete answer, which is right for a local home that simply has no agent state but wrong here. After a wsl --shutdown the cached distro home still resolves, so nothing else marked the scan incomplete: the empty result was memoized for the whole process lifetime and every later generated create in that namespace reissued names spent inside the distro. That is STA-4472 again, reached by a different route. ENOENT now only means "absent" off UNC.
…able 9P route Distrusting every UNC ENOENT fixed the shut-down-distro hole but overshot: a distro where nobody has run Claude genuinely has no ~/.claude/projects, which is the common case for Codex-only users and for anyone running agents from the Windows side. Those namespaces could never report a complete answer, so the one-time seed became a full rescan every 60s for the life of the process — each one re-spawning wsl.exe and taking the single process-wide scan slot from transcript discovery, on a path that runs on every composer open rather than only at create. Probe the parent instead. If it lists, the child really is absent and the answer is complete; if it does not, the route is down and the scan stays retryable. Both directions are pinned: reverting to either of the previous behaviours turns a test red.
The reachability probe checked a single parent, which only disambiguates when ~/.claude exists but ~/.claude/projects does not. The far more common shapes have the ancestors missing too: a distro where Claude has never run has no ~/.claude at all, and a repo with no workspaces yet has neither the workspace root nor its parent. In both, the one-level probe also got ENOENT and called the route unreachable, which is exactly the 60s rescan loop it was added to prevent. Walk up until a listing succeeds, bounded so a pathological path cannot hold the scan slot. One reachable ancestor proves the route is up, so the ENOENT below it is real absence. The test that was supposed to guard this had ~/.claude resolving, so the real shape was never exercised — which is why the defect shipped green. Its fixture now leaves the whole chain absent up to the distro home, and reverting to the one-level probe turns it red.
The shared WSL filesystem gate admits one scan task process-wide, and its stuck-task check matches scan against scan regardless of route. So retirement discovery now queues with — and on a wedged distro can fast-fail — native-chat transcript discovery, which the ungated readdir it replaced never could. Gating is still right: the gate holds the only deadline and permit accounting these UNC reads get, and without it a hung 9P route keeps a libuv thread outright. A dedicated lane would need a third priority, which is a change to the gate rather than to this file. Writing the trade-off down so the next reader does not have to rediscover it.
…te coupling runs both ways The ancestor probe only asks whether a directory is there, but it listed it — enumerating a WSL home over 9P, on the composer-open path, holding the single scan permit while it did. stat answers the same question; the gate already supports the operation. Also corrects the trade-off note added last commit, which recorded only the direction where retirement discovery is the victim. Because the gate stuck-check matches scan against scan regardless of route, the reverse is now true too and is the part this PR introduces: a retirement listing wedged on one distro can fast-fail transcript discovery on a healthy one.
69a0078 to
6bdb604
Compare
|
Too many files changed for review (500 files, 100 file limit). Bypass the limit by tagging |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
💤 Files with no reviewable changes (1)
Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review. 📝 WalkthroughWalkthroughThe change moves retirement-name discovery into a dedicated module. It adds workspace, Claude project, and WSL source handling with completeness tracking. A separate coordinator manages per-store scan caching, timeouts, retries, incomplete results, and stalled operations. The existing backfill path delegates to both modules. New tests cover discovery, WSL behavior, scan state, timeout recovery, retry backoff, and integration wiring. Retired-name tests remain focused on normalization, registry, and backfill behavior. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
🧹 Nitpick comments (2)
src/main/worktree-retirement-discovery.ts (2)
9-10: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider moving these two symbols to break the module cycle.
worktree-name-retirement.tsimportsdiscoverRetiredWorktreeNamesfrom this module, and this module importsnormalizeRetirableGeneratedNameback from it. The cycle is safe today because both bindings are used after module evaluation, but it also inverts the contract direction:RetirementScanResultis produced here and declared in the coordinator.A lower-coupling layout keeps the result type in this module and moves
normalizeRetirableGeneratedNameinto the module that owns creature-name normalization. The coordinator then imports the type, and the cycle disappears.
52-67: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueMulti-paragraph rationale comments in both new modules. Both blocks record design trade-offs and defect history as multi-paragraph source comments. The coding guidelines require concise, brief comments and prefer one line. Keep the invariants a maintainer must not break, and move the narrative to module documentation or the PR description.
src/main/worktree-retirement-discovery.ts#L52-L67: reduce to the refusal contract — report a refusal, never throw, never memoize the hole.src/main/worktree-retirement-backfill-scan.ts#L48-L60: reduce to the two cache invariants — memoize a complete success for the process lifetime, and retry only after the previous listing settles.As per coding guidelines: "Comments must be concise, non-obvious, and brief—prefer one line; do not explain obvious behavior or walk through code."
Source: Coding guidelines
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4ef6f48f-7f77-4fc6-ac9e-c6faa4946b6e
📒 Files selected for processing (8)
src/main/worktree-name-retirement.test.tssrc/main/worktree-name-retirement.tssrc/main/worktree-retirement-backfill-scan.test.tssrc/main/worktree-retirement-backfill-scan.tssrc/main/worktree-retirement-backfill-stall.test.tssrc/main/worktree-retirement-discovery-wsl.test.tssrc/main/worktree-retirement-discovery.test.tssrc/main/worktree-retirement-discovery.ts
💤 Files with no reviewable changes (1)
- src/main/worktree-name-retirement.test.ts
Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.
The rebase onto main kept main's import block, which still pulled readdir and homedir for discovery code this branch moved into worktree-retirement-discovery.ts.
…kfill scan (STA-4472, STA-4473) (stablyai#14924) * fix(worktrees): cover WSL distro history and bound the retirement backfill scan (STA-4472, STA-4473) * fix(worktrees): bound outstanding retirement backfill listings, not just their rate The scan deadline abandons a listing, it cannot cancel one: an unabortable readdir keeps its libuv threadpool thread until the OS releases it. The failure backoff paced retries but never counted the abandoned calls, so a mount that stayed wedged stacked a new stuck thread on every lapse until the four-thread pool starved every other filesystem user in the process. UNC reads were already bounded by the WSL gate's permit accounting; plain SMB/NFS listings were not. Cap the outstanding listings process-wide and serve the memoized failure once the cap is reached. Recovery is preserved: a slot frees as soon as an abandoned listing settles. * fix(worktrees): keep a late retirement listing, and stop deferrals penalising healthy repos Three review findings on the scan bound: - A listing that landed after the 15s deadline had its result discarded. Under the WSL gate that is the common case, not an edge one: the gate admits a single scan at a time and allows it 60s, four times this deadline. The namespace was then left unseeded on exactly the mounts this feature exists to cover. The answer is now kept when it arrives. - A namespace deferred at the outstanding-listing cap never touched the wedged mount, so arming its backoff spread one bad mount's outage to repos on healthy disks. Deferrals no longer memoize; the next create retries as soon as a slot frees. - The cap comment claimed it bounds threadpool starvation. It bounds this module's share only; the WSL gate and its close lane hold threads of their own. Comment corrected. Also stub the WSL resolver in the UNC-root unit test, which otherwise shells out to wsl.exe and boots the developer's distro on a Windows runner. * fix(worktrees): only count stuck retirement listings, and fence the backoff on a monotonic clock Two more review findings on the outstanding-listing cap: - The cap counted every in-flight listing, not just the stuck ones, so it fired on healthy machines. Nested workspaces give each repo its own scan key, so a few first-time backfills are routinely in flight together; the third was rejected and its create then picked a name against an unseeded registry. Only listings that have outlived their deadline occupy a slot now, which is what the cap was always meant to bound — healthy scans finish in milliseconds. - The backoff fence compared wall-clock times. The WSL gate this scan runs under deliberately avoids wall time for exactly this ('would misjudge stuckness across laptop sleep or NTP steps'); a backward step pinned a namespace in its failure memo for the size of the step. Now monotonic. A third finding — that a late listing writing into an entry a retry has replaced loses the answer — was investigated and refuted. An entry is only ever read back through the map, and callers hold the promise rather than the entry, so a write to a replaced entry cannot be observed. No guard added: the test for it passed with and without one. * fix(worktrees): gate retirement rescans per namespace, and keep a partial answer usable Replaces the process-wide listing budget with a per-namespace rule, and stops a refused source throwing away the sources that did read. - A global budget was the wrong shape: one wedged mount spends it on its own retries (lapse, restack, lapse) and then every other namespace — including repos on healthy local disks — is refused for the process lifetime, which is a strictly larger blast radius than the wedge it replaced. A namespace now simply may not start a second listing while its own is still stuck, so a bad mount costs exactly one thread and nothing else is affected. - Rethrowing a gate refusal abandoned the whole scan at the first source. For a WSL repo the UNC workspace root is listed first, so a stuck 9P route also discarded the plain, readable Windows-side bucket scan that needs no distro access — worse than the behaviour before the split. Discovery now returns what it read plus a "complete" flag; the names are used, and only the memoization is withheld so the hole is retried. - An I/O failure was reported as a complete empty listing, so a transient EIO on a redirected or network home memoized "nothing is retired" for the process lifetime. Only ENOENT/ENOTDIR now count as a complete answer. The recovery tests now release the stalled listing rather than leaving it pending forever: a retry while the previous call is still stuck is precisely what stacks threads. * fix(worktrees): keep the scan retryable when a WSL distro home will not resolve Resolving a distro home shells out to wsl.exe, which returns nothing for a stopped or slow distro (the call has a 5s timeout) or when wsl.exe is not resolvable from the Electron process. That case dropped the distro bucket source silently and still reported the scan complete, so the empty answer was memoized for the whole process lifetime. That is the STA-4472 defect re-entering through the back door: the distro is exactly where a WSL workspace's agent history lives, so a workspace whose directory is gone leaves its only surviving evidence unread, and the next generated create reissues that cwd. It does not self-heal either — the scan key is derived from the probe path, which is unchanged by a failed home resolution. An unresolved distro now marks the scan incomplete, which serves the names that were found while leaving the hole to be retried after the backoff. * fix(worktrees): trace a WSL repo's Windows-side workspaces into the distro too Distro discovery keyed only on the workspace root being a UNC path, but a WSL repo can legitimately own workspaces under C:\. computeWorkspaceRootAsync mirrors the workspace dir into the distro only when the distro home resolves at create time; when that wsl.exe call fails it falls back to the drive path, and those workspaces stay on the Windows side. The agent is still spawned through wsl.exe, so its cwd is the drvfs mirror (/mnt/c/...) and its bucket lands in the distro's own ~/.claude/projects, where the host-home scan cannot see it. The scan then reported complete and memoized the empty answer, so the name was reissued and the next occupant inherited the previous conversation — the STA-4472 defect, in the one configuration the UNC check does not cover. Which distro to look in comes from the repo path rather than the workspace root, since that is what still identifies the distro once the root is a drive path. * revert drvfs-mirror discovery, and pin the "no agent state" classification Reverts the previous commit. The drvfs branch traced a WSL repo's Windows-side workspaces into the distro, but its production wiring cannot be pinned: the distro comes from parseWslPath(repo.path), which short-circuits off win32, so no assertion on a Linux or macOS runner can reach it — deleting the wiring line left every test green. Shipping an unpinnable branch is the exact unreached-module shape this PR exists to close, and it is not worth it here: the branch only pays off in a narrow race where getWslHomeAsync fails while the workspace root is computed and then succeeds seconds later during discovery. Whenever the distro home resolves, the root is UNC and the existing path already covers it; whenever it does not, the scan is already reported incomplete and retried. Also adds the missing guard on the other side of the same classification: ENOENT and ENOTDIR mean "no agent state on this machine", which is a complete answer. That is the common case for a fresh or Codex-only install, and misclassifying it as incomplete would turn the one-time seed into a 60s-interval rescan for the life of the process. The expression had no test; it does now. * test(worktrees): make the retirement backoff window a real assertion The test that claimed to cover it settled the stalled listing and re-entered in the same tick, so outstanding cleared only in a later microtask and the no-restack rule answered first. It was a duplicate of the test above it, and the backoff clause it was meant to pin had no coverage at all: deleting the clause left all twelve tests in both files green, so a regression that re-probes a wedged mount on every generated create would have shipped. Flush the microtask so the listing is genuinely settled, then assert both directions — the memo still serves the failure inside the window, and the same call succeeds once the window lapses. * fix(worktrees): stop trusting a UNC ENOENT, which is what a shut-down distro looks like Windows reports an unreachable 9P route as ENOENT, so a distro that has merely been shut down is indistinguishable from one that never held any buckets. wsl.ts already refuses to trust a UNC ENOENT for the same reason, probing inside the distro instead. The classification added earlier called ENOENT a complete answer, which is right for a local home that simply has no agent state but wrong here. After a wsl --shutdown the cached distro home still resolves, so nothing else marked the scan incomplete: the empty result was memoized for the whole process lifetime and every later generated create in that namespace reissued names spent inside the distro. That is STA-4472 again, reached by a different route. ENOENT now only means "absent" off UNC. * fix(worktrees): tell an absent distro directory apart from an unreachable 9P route Distrusting every UNC ENOENT fixed the shut-down-distro hole but overshot: a distro where nobody has run Claude genuinely has no ~/.claude/projects, which is the common case for Codex-only users and for anyone running agents from the Windows side. Those namespaces could never report a complete answer, so the one-time seed became a full rescan every 60s for the life of the process — each one re-spawning wsl.exe and taking the single process-wide scan slot from transcript discovery, on a path that runs on every composer open rather than only at create. Probe the parent instead. If it lists, the child really is absent and the answer is complete; if it does not, the route is down and the scan stays retryable. Both directions are pinned: reverting to either of the previous behaviours turns a test red. * fix(worktrees): walk up to a reachable ancestor, not just one level The reachability probe checked a single parent, which only disambiguates when ~/.claude exists but ~/.claude/projects does not. The far more common shapes have the ancestors missing too: a distro where Claude has never run has no ~/.claude at all, and a repo with no workspaces yet has neither the workspace root nor its parent. In both, the one-level probe also got ENOENT and called the route unreachable, which is exactly the 60s rescan loop it was added to prevent. Walk up until a listing succeeds, bounded so a pathological path cannot hold the scan slot. One reachable ancestor proves the route is up, so the ENOENT below it is real absence. The test that was supposed to guard this had ~/.claude resolving, so the real shape was never exercised — which is why the defect shipped green. Its fixture now leaves the whole chain absent up to the distro home, and reverting to the one-level probe turns it red. * docs(worktrees): record what gating retirement listings costs The shared WSL filesystem gate admits one scan task process-wide, and its stuck-task check matches scan against scan regardless of route. So retirement discovery now queues with — and on a wedged distro can fast-fail — native-chat transcript discovery, which the ungated readdir it replaced never could. Gating is still right: the gate holds the only deadline and permit accounting these UNC reads get, and without it a hung 9P route keeps a libuv thread outright. A dedicated lane would need a third priority, which is a change to the gate rather than to this file. Writing the trade-off down so the next reader does not have to rediscover it. * perf(worktrees): probe reachability with stat, and record that the gate coupling runs both ways The ancestor probe only asks whether a directory is there, but it listed it — enumerating a WSL home over 9P, on the composer-open path, holding the single scan permit while it did. stat answers the same question; the gate already supports the operation. Also corrects the trade-off note added last commit, which recorded only the direction where retirement discovery is the victim. Because the gate stuck-check matches scan against scan regardless of route, the reverse is now true too and is the part this PR introduces: a retirement listing wedged on one distro can fast-fail transcript discovery on a healthy one. * fix(worktrees): drop imports the discovery extraction left unused The rebase onto main kept main's import block, which still pulled readdir and homedir for discovery code this branch moved into worktree-retirement-discovery.ts. * fix(worktrees): drop the last import the discovery extraction left unused
…kfill scan (STA-4472, STA-4473) (stablyai#14924) * fix(worktrees): cover WSL distro history and bound the retirement backfill scan (STA-4472, STA-4473) * fix(worktrees): bound outstanding retirement backfill listings, not just their rate The scan deadline abandons a listing, it cannot cancel one: an unabortable readdir keeps its libuv threadpool thread until the OS releases it. The failure backoff paced retries but never counted the abandoned calls, so a mount that stayed wedged stacked a new stuck thread on every lapse until the four-thread pool starved every other filesystem user in the process. UNC reads were already bounded by the WSL gate's permit accounting; plain SMB/NFS listings were not. Cap the outstanding listings process-wide and serve the memoized failure once the cap is reached. Recovery is preserved: a slot frees as soon as an abandoned listing settles. * fix(worktrees): keep a late retirement listing, and stop deferrals penalising healthy repos Three review findings on the scan bound: - A listing that landed after the 15s deadline had its result discarded. Under the WSL gate that is the common case, not an edge one: the gate admits a single scan at a time and allows it 60s, four times this deadline. The namespace was then left unseeded on exactly the mounts this feature exists to cover. The answer is now kept when it arrives. - A namespace deferred at the outstanding-listing cap never touched the wedged mount, so arming its backoff spread one bad mount's outage to repos on healthy disks. Deferrals no longer memoize; the next create retries as soon as a slot frees. - The cap comment claimed it bounds threadpool starvation. It bounds this module's share only; the WSL gate and its close lane hold threads of their own. Comment corrected. Also stub the WSL resolver in the UNC-root unit test, which otherwise shells out to wsl.exe and boots the developer's distro on a Windows runner. * fix(worktrees): only count stuck retirement listings, and fence the backoff on a monotonic clock Two more review findings on the outstanding-listing cap: - The cap counted every in-flight listing, not just the stuck ones, so it fired on healthy machines. Nested workspaces give each repo its own scan key, so a few first-time backfills are routinely in flight together; the third was rejected and its create then picked a name against an unseeded registry. Only listings that have outlived their deadline occupy a slot now, which is what the cap was always meant to bound — healthy scans finish in milliseconds. - The backoff fence compared wall-clock times. The WSL gate this scan runs under deliberately avoids wall time for exactly this ('would misjudge stuckness across laptop sleep or NTP steps'); a backward step pinned a namespace in its failure memo for the size of the step. Now monotonic. A third finding — that a late listing writing into an entry a retry has replaced loses the answer — was investigated and refuted. An entry is only ever read back through the map, and callers hold the promise rather than the entry, so a write to a replaced entry cannot be observed. No guard added: the test for it passed with and without one. * fix(worktrees): gate retirement rescans per namespace, and keep a partial answer usable Replaces the process-wide listing budget with a per-namespace rule, and stops a refused source throwing away the sources that did read. - A global budget was the wrong shape: one wedged mount spends it on its own retries (lapse, restack, lapse) and then every other namespace — including repos on healthy local disks — is refused for the process lifetime, which is a strictly larger blast radius than the wedge it replaced. A namespace now simply may not start a second listing while its own is still stuck, so a bad mount costs exactly one thread and nothing else is affected. - Rethrowing a gate refusal abandoned the whole scan at the first source. For a WSL repo the UNC workspace root is listed first, so a stuck 9P route also discarded the plain, readable Windows-side bucket scan that needs no distro access — worse than the behaviour before the split. Discovery now returns what it read plus a "complete" flag; the names are used, and only the memoization is withheld so the hole is retried. - An I/O failure was reported as a complete empty listing, so a transient EIO on a redirected or network home memoized "nothing is retired" for the process lifetime. Only ENOENT/ENOTDIR now count as a complete answer. The recovery tests now release the stalled listing rather than leaving it pending forever: a retry while the previous call is still stuck is precisely what stacks threads. * fix(worktrees): keep the scan retryable when a WSL distro home will not resolve Resolving a distro home shells out to wsl.exe, which returns nothing for a stopped or slow distro (the call has a 5s timeout) or when wsl.exe is not resolvable from the Electron process. That case dropped the distro bucket source silently and still reported the scan complete, so the empty answer was memoized for the whole process lifetime. That is the STA-4472 defect re-entering through the back door: the distro is exactly where a WSL workspace's agent history lives, so a workspace whose directory is gone leaves its only surviving evidence unread, and the next generated create reissues that cwd. It does not self-heal either — the scan key is derived from the probe path, which is unchanged by a failed home resolution. An unresolved distro now marks the scan incomplete, which serves the names that were found while leaving the hole to be retried after the backoff. * fix(worktrees): trace a WSL repo's Windows-side workspaces into the distro too Distro discovery keyed only on the workspace root being a UNC path, but a WSL repo can legitimately own workspaces under C:\. computeWorkspaceRootAsync mirrors the workspace dir into the distro only when the distro home resolves at create time; when that wsl.exe call fails it falls back to the drive path, and those workspaces stay on the Windows side. The agent is still spawned through wsl.exe, so its cwd is the drvfs mirror (/mnt/c/...) and its bucket lands in the distro's own ~/.claude/projects, where the host-home scan cannot see it. The scan then reported complete and memoized the empty answer, so the name was reissued and the next occupant inherited the previous conversation — the STA-4472 defect, in the one configuration the UNC check does not cover. Which distro to look in comes from the repo path rather than the workspace root, since that is what still identifies the distro once the root is a drive path. * revert drvfs-mirror discovery, and pin the "no agent state" classification Reverts the previous commit. The drvfs branch traced a WSL repo's Windows-side workspaces into the distro, but its production wiring cannot be pinned: the distro comes from parseWslPath(repo.path), which short-circuits off win32, so no assertion on a Linux or macOS runner can reach it — deleting the wiring line left every test green. Shipping an unpinnable branch is the exact unreached-module shape this PR exists to close, and it is not worth it here: the branch only pays off in a narrow race where getWslHomeAsync fails while the workspace root is computed and then succeeds seconds later during discovery. Whenever the distro home resolves, the root is UNC and the existing path already covers it; whenever it does not, the scan is already reported incomplete and retried. Also adds the missing guard on the other side of the same classification: ENOENT and ENOTDIR mean "no agent state on this machine", which is a complete answer. That is the common case for a fresh or Codex-only install, and misclassifying it as incomplete would turn the one-time seed into a 60s-interval rescan for the life of the process. The expression had no test; it does now. * test(worktrees): make the retirement backoff window a real assertion The test that claimed to cover it settled the stalled listing and re-entered in the same tick, so outstanding cleared only in a later microtask and the no-restack rule answered first. It was a duplicate of the test above it, and the backoff clause it was meant to pin had no coverage at all: deleting the clause left all twelve tests in both files green, so a regression that re-probes a wedged mount on every generated create would have shipped. Flush the microtask so the listing is genuinely settled, then assert both directions — the memo still serves the failure inside the window, and the same call succeeds once the window lapses. * fix(worktrees): stop trusting a UNC ENOENT, which is what a shut-down distro looks like Windows reports an unreachable 9P route as ENOENT, so a distro that has merely been shut down is indistinguishable from one that never held any buckets. wsl.ts already refuses to trust a UNC ENOENT for the same reason, probing inside the distro instead. The classification added earlier called ENOENT a complete answer, which is right for a local home that simply has no agent state but wrong here. After a wsl --shutdown the cached distro home still resolves, so nothing else marked the scan incomplete: the empty result was memoized for the whole process lifetime and every later generated create in that namespace reissued names spent inside the distro. That is STA-4472 again, reached by a different route. ENOENT now only means "absent" off UNC. * fix(worktrees): tell an absent distro directory apart from an unreachable 9P route Distrusting every UNC ENOENT fixed the shut-down-distro hole but overshot: a distro where nobody has run Claude genuinely has no ~/.claude/projects, which is the common case for Codex-only users and for anyone running agents from the Windows side. Those namespaces could never report a complete answer, so the one-time seed became a full rescan every 60s for the life of the process — each one re-spawning wsl.exe and taking the single process-wide scan slot from transcript discovery, on a path that runs on every composer open rather than only at create. Probe the parent instead. If it lists, the child really is absent and the answer is complete; if it does not, the route is down and the scan stays retryable. Both directions are pinned: reverting to either of the previous behaviours turns a test red. * fix(worktrees): walk up to a reachable ancestor, not just one level The reachability probe checked a single parent, which only disambiguates when ~/.claude exists but ~/.claude/projects does not. The far more common shapes have the ancestors missing too: a distro where Claude has never run has no ~/.claude at all, and a repo with no workspaces yet has neither the workspace root nor its parent. In both, the one-level probe also got ENOENT and called the route unreachable, which is exactly the 60s rescan loop it was added to prevent. Walk up until a listing succeeds, bounded so a pathological path cannot hold the scan slot. One reachable ancestor proves the route is up, so the ENOENT below it is real absence. The test that was supposed to guard this had ~/.claude resolving, so the real shape was never exercised — which is why the defect shipped green. Its fixture now leaves the whole chain absent up to the distro home, and reverting to the one-level probe turns it red. * docs(worktrees): record what gating retirement listings costs The shared WSL filesystem gate admits one scan task process-wide, and its stuck-task check matches scan against scan regardless of route. So retirement discovery now queues with — and on a wedged distro can fast-fail — native-chat transcript discovery, which the ungated readdir it replaced never could. Gating is still right: the gate holds the only deadline and permit accounting these UNC reads get, and without it a hung 9P route keeps a libuv thread outright. A dedicated lane would need a third priority, which is a change to the gate rather than to this file. Writing the trade-off down so the next reader does not have to rediscover it. * perf(worktrees): probe reachability with stat, and record that the gate coupling runs both ways The ancestor probe only asks whether a directory is there, but it listed it — enumerating a WSL home over 9P, on the composer-open path, holding the single scan permit while it did. stat answers the same question; the gate already supports the operation. Also corrects the trade-off note added last commit, which recorded only the direction where retirement discovery is the victim. Because the gate stuck-check matches scan against scan regardless of route, the reverse is now true too and is the part this PR introduces: a retirement listing wedged on one distro can fast-fail transcript discovery on a healthy one. * fix(worktrees): drop imports the discovery extraction left unused The rebase onto main kept main's import block, which still pulled readdir and homedir for discovery code this branch moved into worktree-retirement-discovery.ts. * fix(worktrees): drop the last import the discovery extraction left unused
…kfill scan (STA-4472, STA-4473) (stablyai#14924) * fix(worktrees): cover WSL distro history and bound the retirement backfill scan (STA-4472, STA-4473) * fix(worktrees): bound outstanding retirement backfill listings, not just their rate The scan deadline abandons a listing, it cannot cancel one: an unabortable readdir keeps its libuv threadpool thread until the OS releases it. The failure backoff paced retries but never counted the abandoned calls, so a mount that stayed wedged stacked a new stuck thread on every lapse until the four-thread pool starved every other filesystem user in the process. UNC reads were already bounded by the WSL gate's permit accounting; plain SMB/NFS listings were not. Cap the outstanding listings process-wide and serve the memoized failure once the cap is reached. Recovery is preserved: a slot frees as soon as an abandoned listing settles. * fix(worktrees): keep a late retirement listing, and stop deferrals penalising healthy repos Three review findings on the scan bound: - A listing that landed after the 15s deadline had its result discarded. Under the WSL gate that is the common case, not an edge one: the gate admits a single scan at a time and allows it 60s, four times this deadline. The namespace was then left unseeded on exactly the mounts this feature exists to cover. The answer is now kept when it arrives. - A namespace deferred at the outstanding-listing cap never touched the wedged mount, so arming its backoff spread one bad mount's outage to repos on healthy disks. Deferrals no longer memoize; the next create retries as soon as a slot frees. - The cap comment claimed it bounds threadpool starvation. It bounds this module's share only; the WSL gate and its close lane hold threads of their own. Comment corrected. Also stub the WSL resolver in the UNC-root unit test, which otherwise shells out to wsl.exe and boots the developer's distro on a Windows runner. * fix(worktrees): only count stuck retirement listings, and fence the backoff on a monotonic clock Two more review findings on the outstanding-listing cap: - The cap counted every in-flight listing, not just the stuck ones, so it fired on healthy machines. Nested workspaces give each repo its own scan key, so a few first-time backfills are routinely in flight together; the third was rejected and its create then picked a name against an unseeded registry. Only listings that have outlived their deadline occupy a slot now, which is what the cap was always meant to bound — healthy scans finish in milliseconds. - The backoff fence compared wall-clock times. The WSL gate this scan runs under deliberately avoids wall time for exactly this ('would misjudge stuckness across laptop sleep or NTP steps'); a backward step pinned a namespace in its failure memo for the size of the step. Now monotonic. A third finding — that a late listing writing into an entry a retry has replaced loses the answer — was investigated and refuted. An entry is only ever read back through the map, and callers hold the promise rather than the entry, so a write to a replaced entry cannot be observed. No guard added: the test for it passed with and without one. * fix(worktrees): gate retirement rescans per namespace, and keep a partial answer usable Replaces the process-wide listing budget with a per-namespace rule, and stops a refused source throwing away the sources that did read. - A global budget was the wrong shape: one wedged mount spends it on its own retries (lapse, restack, lapse) and then every other namespace — including repos on healthy local disks — is refused for the process lifetime, which is a strictly larger blast radius than the wedge it replaced. A namespace now simply may not start a second listing while its own is still stuck, so a bad mount costs exactly one thread and nothing else is affected. - Rethrowing a gate refusal abandoned the whole scan at the first source. For a WSL repo the UNC workspace root is listed first, so a stuck 9P route also discarded the plain, readable Windows-side bucket scan that needs no distro access — worse than the behaviour before the split. Discovery now returns what it read plus a "complete" flag; the names are used, and only the memoization is withheld so the hole is retried. - An I/O failure was reported as a complete empty listing, so a transient EIO on a redirected or network home memoized "nothing is retired" for the process lifetime. Only ENOENT/ENOTDIR now count as a complete answer. The recovery tests now release the stalled listing rather than leaving it pending forever: a retry while the previous call is still stuck is precisely what stacks threads. * fix(worktrees): keep the scan retryable when a WSL distro home will not resolve Resolving a distro home shells out to wsl.exe, which returns nothing for a stopped or slow distro (the call has a 5s timeout) or when wsl.exe is not resolvable from the Electron process. That case dropped the distro bucket source silently and still reported the scan complete, so the empty answer was memoized for the whole process lifetime. That is the STA-4472 defect re-entering through the back door: the distro is exactly where a WSL workspace's agent history lives, so a workspace whose directory is gone leaves its only surviving evidence unread, and the next generated create reissues that cwd. It does not self-heal either — the scan key is derived from the probe path, which is unchanged by a failed home resolution. An unresolved distro now marks the scan incomplete, which serves the names that were found while leaving the hole to be retried after the backoff. * fix(worktrees): trace a WSL repo's Windows-side workspaces into the distro too Distro discovery keyed only on the workspace root being a UNC path, but a WSL repo can legitimately own workspaces under C:\. computeWorkspaceRootAsync mirrors the workspace dir into the distro only when the distro home resolves at create time; when that wsl.exe call fails it falls back to the drive path, and those workspaces stay on the Windows side. The agent is still spawned through wsl.exe, so its cwd is the drvfs mirror (/mnt/c/...) and its bucket lands in the distro's own ~/.claude/projects, where the host-home scan cannot see it. The scan then reported complete and memoized the empty answer, so the name was reissued and the next occupant inherited the previous conversation — the STA-4472 defect, in the one configuration the UNC check does not cover. Which distro to look in comes from the repo path rather than the workspace root, since that is what still identifies the distro once the root is a drive path. * revert drvfs-mirror discovery, and pin the "no agent state" classification Reverts the previous commit. The drvfs branch traced a WSL repo's Windows-side workspaces into the distro, but its production wiring cannot be pinned: the distro comes from parseWslPath(repo.path), which short-circuits off win32, so no assertion on a Linux or macOS runner can reach it — deleting the wiring line left every test green. Shipping an unpinnable branch is the exact unreached-module shape this PR exists to close, and it is not worth it here: the branch only pays off in a narrow race where getWslHomeAsync fails while the workspace root is computed and then succeeds seconds later during discovery. Whenever the distro home resolves, the root is UNC and the existing path already covers it; whenever it does not, the scan is already reported incomplete and retried. Also adds the missing guard on the other side of the same classification: ENOENT and ENOTDIR mean "no agent state on this machine", which is a complete answer. That is the common case for a fresh or Codex-only install, and misclassifying it as incomplete would turn the one-time seed into a 60s-interval rescan for the life of the process. The expression had no test; it does now. * test(worktrees): make the retirement backoff window a real assertion The test that claimed to cover it settled the stalled listing and re-entered in the same tick, so outstanding cleared only in a later microtask and the no-restack rule answered first. It was a duplicate of the test above it, and the backoff clause it was meant to pin had no coverage at all: deleting the clause left all twelve tests in both files green, so a regression that re-probes a wedged mount on every generated create would have shipped. Flush the microtask so the listing is genuinely settled, then assert both directions — the memo still serves the failure inside the window, and the same call succeeds once the window lapses. * fix(worktrees): stop trusting a UNC ENOENT, which is what a shut-down distro looks like Windows reports an unreachable 9P route as ENOENT, so a distro that has merely been shut down is indistinguishable from one that never held any buckets. wsl.ts already refuses to trust a UNC ENOENT for the same reason, probing inside the distro instead. The classification added earlier called ENOENT a complete answer, which is right for a local home that simply has no agent state but wrong here. After a wsl --shutdown the cached distro home still resolves, so nothing else marked the scan incomplete: the empty result was memoized for the whole process lifetime and every later generated create in that namespace reissued names spent inside the distro. That is STA-4472 again, reached by a different route. ENOENT now only means "absent" off UNC. * fix(worktrees): tell an absent distro directory apart from an unreachable 9P route Distrusting every UNC ENOENT fixed the shut-down-distro hole but overshot: a distro where nobody has run Claude genuinely has no ~/.claude/projects, which is the common case for Codex-only users and for anyone running agents from the Windows side. Those namespaces could never report a complete answer, so the one-time seed became a full rescan every 60s for the life of the process — each one re-spawning wsl.exe and taking the single process-wide scan slot from transcript discovery, on a path that runs on every composer open rather than only at create. Probe the parent instead. If it lists, the child really is absent and the answer is complete; if it does not, the route is down and the scan stays retryable. Both directions are pinned: reverting to either of the previous behaviours turns a test red. * fix(worktrees): walk up to a reachable ancestor, not just one level The reachability probe checked a single parent, which only disambiguates when ~/.claude exists but ~/.claude/projects does not. The far more common shapes have the ancestors missing too: a distro where Claude has never run has no ~/.claude at all, and a repo with no workspaces yet has neither the workspace root nor its parent. In both, the one-level probe also got ENOENT and called the route unreachable, which is exactly the 60s rescan loop it was added to prevent. Walk up until a listing succeeds, bounded so a pathological path cannot hold the scan slot. One reachable ancestor proves the route is up, so the ENOENT below it is real absence. The test that was supposed to guard this had ~/.claude resolving, so the real shape was never exercised — which is why the defect shipped green. Its fixture now leaves the whole chain absent up to the distro home, and reverting to the one-level probe turns it red. * docs(worktrees): record what gating retirement listings costs The shared WSL filesystem gate admits one scan task process-wide, and its stuck-task check matches scan against scan regardless of route. So retirement discovery now queues with — and on a wedged distro can fast-fail — native-chat transcript discovery, which the ungated readdir it replaced never could. Gating is still right: the gate holds the only deadline and permit accounting these UNC reads get, and without it a hung 9P route keeps a libuv thread outright. A dedicated lane would need a third priority, which is a change to the gate rather than to this file. Writing the trade-off down so the next reader does not have to rediscover it. * perf(worktrees): probe reachability with stat, and record that the gate coupling runs both ways The ancestor probe only asks whether a directory is there, but it listed it — enumerating a WSL home over 9P, on the composer-open path, holding the single scan permit while it did. stat answers the same question; the gate already supports the operation. Also corrects the trade-off note added last commit, which recorded only the direction where retirement discovery is the victim. Because the gate stuck-check matches scan against scan regardless of route, the reverse is now true too and is the part this PR introduces: a retirement listing wedged on one distro can fast-fail transcript discovery on a healthy one. * fix(worktrees): drop imports the discovery extraction left unused The rebase onto main kept main's import block, which still pulled readdir and homedir for discovery code this branch moved into worktree-retirement-discovery.ts. * fix(worktrees): drop the last import the discovery extraction left unused


Fixes STA-4472 (P0) and STA-4473 (P1). Both regressions from #14350, and both defects of the same
component: the one-time retirement backfill scan.
Merge order — read this first
Merge strictly bottom-up. #14919 is a separate PR on purpose: it reverses a deliberate #14350
product decision (a deliberately typed pool name such as
nautilusis now redirected tonautilus-2when that cwd is retired, and typed pool-shaped names are now recorded as spent). Ithas to stay droppable on its own without losing #14917's two P0/P1 tombstone fixes. This PR sits on
top of that judgement; see the sequencing note below for why it should not lag far behind it.
STA-4472 — WSL retirement backfill misses distro Claude history
discoverRetiredWorktreeNamesread only the Windows-side~/.claude/projects. A WSL workspace'sagent is spawned through
wsl.exe, so it runs inside the distro: its cwd is the Linux path(
/home/ada/orca/workspaces/nautilus), not the UNC spelling, and its bucket lands in the distro'sown
~/.claude/projects. Once the workspace directory is deleted, that distro-local bucket is theonly durable evidence the name is spent — and backfill never looked at it, so create reissued the
cwd and handed the new workspace the old conversation.
The fix generalises the single host bucket directory into a list of sources, each paired with the
encoded cwds it would hold:
<wslHome>/.claude/projects, with that distro's rootsencoded from their Linux paths.
A stopped distro (
getWslHomeAsyncreturns null) simply contributes no source — the host-sideretirements it can still see are unaffected.
The distro's own
CLAUDE_CONFIG_DIRis not readable from the Windows side, so only the defaultlocation is scanned there. That is the same best-effort contract the rest of this discovery already
documents.
STA-4473 — generated-name create can hang on retirement backfill
The scan Promise was cached in a
WeakMapforever and itsreaddirhad no deadline. One stalledNFS/SMB/WSL UNC listing blocked that create and every later generated-name create for the
namespace until Orca restarted. WSL UNC also bypassed the bounded 9P gate that every other WSL
filesystem consumer goes through.
Three changes, now in
src/main/worktree-retirement-backfill-scan.ts:(
getRetiredNameRegistryForRepo) already catches and warns, so create proceeds on the storedregistry.
readdirkeeps holding a libuv threadpool thread, so retrying on every create would starve thepool (default size 4) and take the whole process's filesystem access down. A success is still
memoized for the process lifetime — a name never un-spends.
wslGatedReaddir(path, 'scan'), the existingwsl-transcript-fs-gate. Off UNC it is a plainreaddir, so nothing else changes. A gate refusalnow propagates rather than being swallowed: swallowing it would memoize a half-read answer
forever, which under-retires — the one direction that leaks history.
Does this close STA-4471's widened exposure? Yes — but the gap between merges is real
#14919 loads the retired-name registry for any pool-shaped name, not just one the client flagged
as generated. That reaches
ensureRetiredWorktreeNamesBackfilled, so it widens the set of createsthat can hit STA-4473's deadline-less scan: before, only generated-name creates paid for it; after,
a user typing an ordinary pool word (
orca,runner,sole) on a stalled NFS/SMB/WSL-UNCworkspace root pays for it too.
This PR closes that exposure completely, and for the widened set as much as the original one —
the bound sits in
ensureRetiredWorktreeNamesBackfilled, below the point where #14919's wideninghappens, so it cannot be bypassed by which caller arrived:
So merging #14919 without #14924 leaves a real window, in which a typed pool-shaped name can
hang create indefinitely on a stalled mount — a regression #14919 introduces and only this PR
retires. If the two cannot land together, the safe options are (a) merge #14924 immediately after
#14919 and ship no build between them, or (b) restack this PR onto #14917 so the bound lands
before the widening. Option (b) is a clean restack — this PR does not depend on #14919's code, only
on its position in the stack — but it is a shape change, so it is flagged here rather than done.
Rebased onto the current #14919
This branch previously carried the pre-split commits
46294c668dand7dd1413a66, orphaned when#14917/#14919 were rebased. Those two edit
src/main/persistence.ts, which onmainis now a9-line re-export barrel — so merging this PR as it stood would have reintroduced the exact dead-code
defect #14917 exists to eliminate: the P0 retirement fix landing in a shim where it runs nowhere,
while still typechecking and still passing every test. Green, and wrong.
Dropped both (their content is on the new base, re-homed into
persistence/loading-store/store.tsand
persistence/leasing-ssh-ptys/ssh-target-reassignment.ts). This PR is now a single commit on6ee943dee3.The rebase itself was silently clean — the two files this PR touches were untouched by the
persistence split, so git had nothing to say. That is precisely why liveness was re-measured from
scratch rather than inferred from a green rebase.
Non-vacuity — and why the usual instrument fails here
Reverting the production files to the base and keeping the tests gives:
0 behavioural failures, 4 load failures. That is the weakest possible result, and it is not
evidence of a vacuous fix — it is the instrument failing. This PR is largely an extraction: the
production code the tests exercise moves into new modules, so reverting it deletes the modules and
the four new suites cannot import anything. A load failure says "the file is gone", not "the
behaviour is gone".
So the evidence here is the mutation matrix. Each row reverts or breaks exactly one thing and names
the tests that die:
worktree-name-retirement.tsalone — new modules present but unwiredmatches a WSL workspace's bucket inside the distrobackfill-scan, both stall testsretries a timed-out namespace once its backoff lapses,recovers the namespace once the mount comes backfails the scan when the gate refuses, rather than memoizing a half-read answerThe first row is the one that matters most, and it is the check a clean rebase cannot give you: with
worktree-name-retirement.tsreverted, the new modules still exist and still pass all their owntests — they are just not called. Three tests notice. Without them this PR could ship as dead code.
A coverage gap this pass found and closed
Every WSL test called
discoverRetiredWorktreeNamesdirectly. All of them stayed green with thewiring reverted, so nothing asserted that
ensureRetiredWorktreeNamesBackfilled— the only callerproduction has — actually reaches the distro-aware discovery. STA-4472's fix could have landed in an
unreached module and every test would still have passed.
Added
reaches distro discovery from the real backfill, not only when called directly, which drivesthe real entry point and asserts the distro-local name is merged into the store. It dies under both
the wiring revert and the WSL-branch mutation.
One detail worth knowing for anyone extending these: it routes through a UNC
workspaceDirrather than a UNC repo path, because
wsl.ts'sparseWslPathreturns null offwin32. Goingthrough the repo path would make the test assert nothing on the Linux and macOS CI runners while
looking like it passed. The distro half of discovery keys on the root string
(
shared/wsl-paths.parseWslUncPath, not platform-gated), so this exercises the real code path.Gates
vitest— 14 affected suites across the whole stacktsc --noEmit× node/cli/weboxlinton changed filesoxlint --config …native-plugins… --deny-warningsoxlint --type-aware --config …type-aware… --deny-warningscheck:max-lines-ratchetoxfmtThe numbers in the previous revision of this description were measured against the pre-split
base and no longer describe this branch; everything above was re-measured after the rebase.
What is test-proven vs. reasoned
Test-proven: a deleted WSL workspace's name stays spent via the distro's own bucket, through the
real backfill entry point; a Windows-side root is not gated; a stopped distro still yields the
host-side retirements; the scan gives up at the deadline instead of hanging; a failed namespace
retries after the backoff instead of wedging until restart; one namespace's stall does not fail
another; a gate refusal propagates rather than memoizing a half-read answer.
Reasoned, not test-proven: that 15s and 60s are the right constants; that libuv threadpool
starvation is the failure mode that makes plain eviction insufficient (argued from the pool's
default size of 4 and
readdirbeing unabortable, not observed); that a real stalled SMB/NFS mountbehaves like the never-settling
readdirthe tests substitute. No test runs against a genuinelystalled network filesystem, and none runs on Windows against a real distro.
Shape
worktree-name-retirement.tscrossed the 300-line cap, so discovery moved toworktree-retirement-discovery.ts(read on-disk evidence → set of spent names) and the memo/deadlinepolicy to
worktree-retirement-backfill-scan.ts. Nomax-linesdisable.Two guard tests are deliberately vacuous against unfixed code and non-vacuous against a naive fix:
"still reads the Windows-side home for a WSL root when the distro home cannot be resolved" (fails if
the distro source replaces the host source) and "leaves no listing ungated when the workspace root
is on the Windows side" (fails if the gate is applied unconditionally).
🤖 Generated with Claude Code