Skip to content

fix(worktrees): cover WSL distro history and bound the retirement backfill scan (STA-4472, STA-4473) - #14924

Merged
brennanb2025 merged 16 commits into
mainfrom
brennanb2025/fix-4472-4473
Aug 20, 2026
Merged

brennanb2025 merged 16 commits into
mainfrom
brennanb2025/fix-4472-4473

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Aug 16, 2026 •

Copy link
Copy Markdown
Contributor
Files Added Deleted Net
Test 5 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​763 $\color{#cf222e}{\Huge{\mathbf{−}}}$​171 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​592
Prod 3 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​357 $\color{#cf222e}{\Huge{\mathbf{−}}}$​110 $\color{#1a7f37}{\Huge{\mathbf{+}}}$​247

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

#14917  (STA-4449 P0 + STA-4491 P1)  → main
  └── #14919  (STA-4471 P0)          → #14917
        └── #14924  (this PR)        → #14919
#14926  (STA-4479/4480 P2)           → main   — independent, mobile-only

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 nautilus is now redirected to
nautilus-2 when that cwd is retired, and typed pool-shaped names are now recorded as spent). It
has 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

discoverRetiredWorktreeNames read only the Windows-side ~/.claude/projects. A WSL workspace's
agent 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's
own ~/.claude/projects. Once the workspace directory is deleted, that distro-local bucket is the
only 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:

  • the Windows-side home, with every root encoded as before (unchanged, existing tests still pass);
  • for each WSL distro among the roots, <wslHome>/.claude/projects, with that distro's roots
    encoded from their Linux paths.

A stopped distro (getWslHomeAsync returns null) simply contributes no source — the host-side
retirements it can still see are unaffected.

The distro's own CLAUDE_CONFIG_DIR is not readable from the Windows side, so only the default
location 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 WeakMap forever and its readdir had no deadline. One stalled
NFS/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:

  • Deadline (15s). Create degrades to "seed nothing" instead of freezing; the caller
    (getRetiredNameRegistryForRepo) already catches and warns, so create proceeds on the stored
    registry.
  • Failed-scan eviction with a backoff (60s). Plain eviction was not enough: an unabortable
    readdir keeps holding a libuv threadpool thread, so retrying on every create would starve the
    pool (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.
  • UNC reads routed through wslGatedReaddir(path, 'scan'), the existing
    wsl-transcript-fs-gate. Off UNC it is a plain readdir, so nothing else changes. A gate refusal
    now 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 creates
that 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-UNC
workspace 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 widening
happens, so it cannot be bypassed by which caller arrived:

before this PR after
stalled listing create hangs forever rejects after 15s, create proceeds unseeded
every later create in that namespace wedged until app restart retries after 60s

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 46294c668d and 7dd1413a66, orphaned when
#14917/#14919 were rebased. Those two edit src/main/persistence.ts, which on main is now a
9-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.ts
and persistence/leasing-ssh-ptys/ssh-target-reassignment.ts). This PR is now a single commit on
6ee943dee3.

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:

Test Files  4 failed | 4 passed (8)
     Tests  56 passed (56)

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:

Mutation Tests killed
revert worktree-name-retirement.ts alone — new modules present but unwired 3 — both stall tests (30s timeout, i.e. the literal STA-4473 hang) + the WSL wiring test
discovery drops the WSL distro branch 3 — 2 WSL + matches a WSL workspace's bucket inside the distro
scan deadline removed 5 — 3 in backfill-scan, both stall tests
failed scan never becomes retryable (the original forever-cache) 2 — retries a timed-out namespace once its backoff lapses, recovers the namespace once the mount comes back
gate refusal swallowed instead of rethrown 1 — fails the scan when the gate refuses, rather than memoizing a half-read answer

The first row is the one that matters most, and it is the check a clean rebase cannot give you: with
worktree-name-retirement.ts reverted, the new modules still exist and still pass all their own
tests — 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 discoverRetiredWorktreeNames directly. All of them stayed green with the
wiring reverted, so nothing asserted that ensureRetiredWorktreeNamesBackfilled — the only caller
production 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 drives
the 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 workspaceDir
rather than a UNC repo path, because wsl.ts's parseWslPath returns null off win32. Going
through 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

Gate Result
vitest — 14 affected suites across the whole stack 1288 passed, 1 skipped
tsc --noEmit × node/cli/web exit 0
oxlint on changed files exit 0
oxlint --config …native-plugins… --deny-warnings exit 0
oxlint --type-aware --config …type-aware… --deny-warnings exit 0
check:max-lines-ratchet OK, no new bypasses
oxfmt clean

The 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 readdir being unabortable, not observed); that a real stalled SMB/NFS mount
behaves like the never-settling readdir the tests substitute. No test runs against a genuinely
stalled network filesystem, and none runs on Windows against a real distro.

Shape

worktree-name-retirement.ts crossed the 300-line cap, so discovery moved to
worktree-retirement-discovery.ts (read on-disk evidence → set of spent names) and the memo/deadline
policy to worktree-retirement-backfill-scan.ts. No max-lines disable.

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

@OrcaWin

OrcaWin commented Aug 17, 2026

Copy link
Copy Markdown
Collaborator

BEFORE — With distro-local agent-history discovery disabled, the create-worktree composer still proposes nautilus for this WSL project even though a conversation bucket for that working directory already exists inside the distro.

Local screenshot (upload blocked; gh image could not obtain a GitHub session token on this host): .qa/before-wsl-name-reissued.png

AFTER — With the distro's agent-history directory included as a discovery source, nautilus is retired and the composer proposes seahorse instead.

Local screenshot (upload blocked): .qa/after-wsl-name-retired.png

Notes: window.api.worktrees.listRetiredNames returned {names:["nautilus"]} with the fix and {names:[]} after the WSL scan was temporarily no-op'd (same on-disk bucket). The name field is optional and stays blank until create; the values shown are the generated seeds that API result selects (first unused pool name).

@brennanb2025

Copy link
Copy Markdown
Contributor Author

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
CDP port). Same WSL project (\\wsl.localhost\Ubuntu-24.04\home\neil\qa-repo), same host row, same
dialog in both shots — the only difference is whether distro-local agent history is a discovery source.

Setup: an agent conversation bucket for the working directory …/orca/workspaces/nautilus exists
inside the distro (~/.claude/projects/-home-neil-orca-workspaces-nautilus), while the workspace
directory itself is gone. That bucket is the only surviving evidence the name is spent.

BEFORE — distro-local history excluded from discovery (the STA-4472 defect). The composer still
proposes nautilus, so creating here would hand the next occupant the previous conversation.

before-wsl-name-reissued.png

AFTER — with this PR, the distro's agent-history directory is a discovery source. nautilus is
recognised as spent and the composer proposes seahorse instead.

after-wsl-name-retired.png

Non-visual validation on the same host

  • All 79 pre-existing retirement tests pass natively on win32 (where parseWslPath is live; it
    short-circuits off win32, so those paths assert nothing on Linux/macOS CI runners).
  • A zero-mock live check drove the real production entry point ensureRetiredWorktreeNamesBackfilled
    with real wsl.exe home resolution and a real 9P UNC listing: the distro bucket was discovered and
    merged in 2 ms. Scanning only the Windows home on the same machine did not see it, which pins
    that the distro half is doing real work rather than the Windows-side scan covering for it.

@brennanb2025
brennanb2025 force-pushed the brennanb2025/fix-4472-4473 branch from 4842f2d to 4549697 Compare August 17, 2026 04:35
@brennanb2025

Copy link
Copy Markdown
Contributor Author

Review loop complete — 14 rounds, 13 fix commits

Two consecutive final rounds reported no correctness bug, and the last one independently
mutation-verified that the guards are not vacuously covered and that the distro branch is live in
production rather than dead code.

What the rounds found and fixed

The original commit's bound was a deadline plus a 60s failure backoff. That paces retries but does
not bound them: the deadline abandons a listing, it cannot cancel one, and an unabortable readdir
keeps its libuv threadpool thread until the OS releases it. Successive fixes worked through:

  1. A process-wide cap on outstanding listings — then replaced, because a single wedged mount spends
    the whole budget on its own retries and starves every healthy repo. Now a namespace 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.
  2. A listing that lands after the deadline is kept rather than 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.
  3. A refused source no longer throws away the sources that did read. For a WSL repo the UNC
    workspace root is listed first, so a stuck 9P route was also discarding the plain, readable
    Windows-side bucket scan. Discovery now returns what it read plus a complete flag; only the
    memoization is withheld.
  4. An I/O failure was being reported as a complete empty listing, so a transient EIO memoized
    "nothing is retired" permanently.
  5. A UNC ENOENT is no longer trusted on its own — Windows reports an unreachable 9P route that
    way, so wsl --shutdown looked identical to a distro that never held buckets. Reachability is
    settled by walking up to an ancestor that exists (via stat, not a listing).
  6. The backoff fence moved to a monotonic clock, matching the gate's own deliberate choice.

One change was reverted: tracing a WSL repo's Windows-side workspaces through the drvfs mirror.
Its production wiring keys on parseWslPath(repo.path), which short-circuits off win32, so no
assertion on a Linux or macOS runner could reach it — deleting the wiring line left every test
green. That is the unreached-module shape this PR exists to close, so it was removed rather than
shipped unpinned.

Platform validation — real Windows host, real WSL distro (Ubuntu-24.04)

  • All shipped retirement suites pass natively on win32, where parseWslPath is actually live.
  • A zero-mock live check drove the real production entry point ensureRetiredWorktreeNamesBackfilled
    with real wsl.exe home resolution and a real 9P UNC listing: the distro bucket was discovered
    and merged in 2 ms. Scanning only the Windows home on the same machine did not see it.
  • Re-run at each subsequent HEAD; still green after every change above.
  • Screenshots of the rendered surface (composer proposes nautilus → seahorse) are in the
    comment above.

Evidence quality

Whole-file production revert is not a usable instrument here — reverting deletes the extracted
modules, so the suites cannot import and the result is 0 behavioural failures + 4 load failures.
The evidence is a mutation matrix instead: every load-bearing behaviour was individually reverted
and confirmed to turn a test red — the no-restack rule, the late-landing keep, the deferral policy,
the complete flag, the incomplete-memoization rule, the distro source, the ENOENT classification
(both directions), the ancestor-walk depth, and the backoff window. Two vacuous tests were found
this way and fixed: one asserted the backoff while actually re-entering in the same tick, and one
had a fixture where ~/.claude existed, which is not the shape a real distro takes.

Residual risk — accepted, not fixed

  • Gate lane coupling (raised in most rounds, deliberately not changed). Retirement listings now
    share the WSL gate's single process-wide scan permit with native-chat transcript discovery, and
    the gate's stuck-task check matches scan-against-scan regardless of route. So a retirement listing
    wedged on one distro can fast-fail transcript discovery on a healthy one — something the ungated
    readdir it replaces could not do. Gating is still correct (it holds the only deadline and permit
    accounting these UNC reads get), but a dedicated lane needs a third gate priority, which is a
    change to the gate rather than to this PR. Recorded in the code.
  • A permanently unreadable source never reaches a terminal state. An EACCES on a redirected home,
    or a distro that was unregistered, keeps the namespace incomplete, so discovery re-runs after each
    60s backoff for the session instead of giving up. Correct direction (under-retiring is the one that
    leaks) but it is no longer strictly a "one-time" seed for those sources.
  • A WSL repo whose workspace root fell back to the Windows side still has its distro buckets
    unread, and that scan memoizes as complete. Narrow — it requires the distro home to fail to resolve
    at create time — and no worse than before this PR, which missed all distro history.
  • Module cycle between worktree-retirement-discovery and worktree-name-retirement
    (normalizeRetirableGeneratedName flows back). Safe today because both bindings are hoisted
    function declarations used only at call time; moving that predicate to a leaf module would remove
    the footgun.

Stacking

I agree with the earlier recommendation to land this before #14919 rather than after. The two
have zero file overlap and no import coupling in either direction, so the restack is mechanically
clean. #14919 widens which names pay for the backfill scan, so landing the bound first removes the
standing "never ship a build between them" constraint, which otherwise depends on a human remembering
it through a merge queue. Worth materializing and running the suites on the restacked branches before
merging — file-level cleanliness is not a green build.

…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.
@brennanb2025
brennanb2025 force-pushed the brennanb2025/fix-4472-4473 branch from 69a0078 to 6bdb604 Compare August 20, 2026 07:41
@brennanb2025
brennanb2025 changed the base branch from brennanb2025/fix-4471 to main August 20, 2026 07:41
@greptile-apps

greptile-apps Bot commented Aug 20, 2026

Copy link
Copy Markdown

Too many files changed for review (500 files, 100 file limit).

Bypass the limit by tagging @greptile-apps to review.

@coderabbitai

coderabbitai Bot commented Aug 20, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c408e930-ee91-41d2-89f4-80479a188556

📥 Commits

Reviewing files that changed from the base of the PR and between 2e3c99a and fb731a5.

📒 Files selected for processing (1)
  • src/main/worktree-name-retirement.ts
💤 Files with no reviewable changes (1)
  • src/main/worktree-name-retirement.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.


📝 Walkthrough

Walkthrough

The 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)
Check name Status Explanation
Docstring Coverage ✅ Passed Docstring coverage is 82.35% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly summarizes the PR's two main changes: WSL distro history discovery and bounded retirement backfill scans.
Description check ✅ Passed The description thoroughly explains the changes, reasons, linked issues, testing, risks, merge order, and AI use, despite not reproducing every template heading.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (2)
src/main/worktree-retirement-discovery.ts (2)

9-10: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider moving these two symbols to break the module cycle.

worktree-name-retirement.ts imports discoverRetiredWorktreeNames from this module, and this module imports normalizeRetirableGeneratedName back from it. The cycle is safe today because both bindings are used after module evaluation, but it also inverts the contract direction: RetirementScanResult is produced here and declared in the coordinator.

A lower-coupling layout keeps the result type in this module and moves normalizeRetirableGeneratedName into the module that owns creature-name normalization. The coordinator then imports the type, and the cycle disappears.


52-67: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Multi-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

📥 Commits

Reviewing files that changed from the base of the PR and between 2e895da and 6bdb604.

📒 Files selected for processing (8)
  • src/main/worktree-name-retirement.test.ts
  • src/main/worktree-name-retirement.ts
  • src/main/worktree-retirement-backfill-scan.test.ts
  • src/main/worktree-retirement-backfill-scan.ts
  • src/main/worktree-retirement-backfill-stall.test.ts
  • src/main/worktree-retirement-discovery-wsl.test.ts
  • src/main/worktree-retirement-discovery.test.ts
  • src/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.
@brennanb2025
brennanb2025 merged commit 21b6619 into main Aug 20, 2026
47 checks passed
paidaxingyo666 pushed a commit to paidaxingyo666/Manta that referenced this pull request Aug 21, 2026
…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
dallascrilley pushed a commit to dallascrilley/orca that referenced this pull request Aug 27, 2026
…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
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
…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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants