fix(worktrees): use Session History's Claude bucket rules when retiring names

Retirement backfill matched Claude project buckets with the old encoder, so it
missed hashed long-path buckets, root workspace folders and the \\wsl$\ share
spelling. Use the shared bucket prefixes, and read the cwd of a hashed bucket
to recover the workspace name its name no longer carries.
This commit is contained in:
Kelvin Amoaba
2026-11-08 22:57:05 +00:00
parent a30768edd0
commit be39a413f6
4 changed files with 157 additions and 31 deletions
@@ -29,7 +29,7 @@ export function isClaudeProjectDirInScope(
}
// Claude Code names a longer encoded path's bucket `<first 200 characters>-<hash>`; older versions kept the full name.
const CLAUDE_BUCKET_NAME_MAX_LENGTH = 200
export const CLAUDE_BUCKET_NAME_MAX_LENGTH = 200
/** Bucket-name prefixes for a scope, including the 200-character cut Claude Code makes for long paths. */
export function claudeProjectBucketScopePrefixes(pathValue: string): string[] {
@@ -43,21 +43,29 @@ export function claudeProjectBucketScopePrefixes(pathValue: string): string[] {
/** Like isClaudeProjectDirInScope, but a root (`-`, `C--`) keeps its separator, so it prefixes every bucket. */
export function isClaudeProjectBucketInScope(
projectDirName: string,
scopePrefixes: ReadonlySet<string>
scopePrefixes: Iterable<string>
): boolean {
for (const prefix of scopePrefixes) {
const isRoot = prefix === '-' || /^[A-Za-z]--$/.test(prefix)
if (
isRoot
? projectDirName.startsWith(prefix)
: isClaudeProjectDirInScope(projectDirName, [prefix])
) {
if (claudeProjectBucketNameBelowScope(projectDirName, prefix) !== null) {
return true
}
}
return false
}
/** The encoded path below one scope prefix (`''` for the scope's own bucket), or null when the bucket is outside it. */
export function claudeProjectBucketNameBelowScope(
projectDirName: string,
scopePrefix: string
): string | null {
if (projectDirName === scopePrefix) {
return ''
}
const isRoot = scopePrefix === '-' || /^[A-Za-z]--$/.test(scopePrefix)
const head = isRoot ? scopePrefix : `${scopePrefix}-`
return projectDirName.startsWith(head) ? projectDirName.slice(head.length) : null
}
/** Transcripts sit in project buckets (depth 0); `<session id>/` folders below hold only subagent and tool output. */
export function isClaudeProjectBucketDirectory(_name: string, depth: number): boolean {
return depth === 0
@@ -138,6 +138,32 @@ describe('retirement discovery on WSL', () => {
}
})
// A distro-root workspace folder encodes to the root prefix `-` on the Linux side.
it.each([
['a host bucket under the older \\\\wsl$\\ spelling', 'host', `--wsl--ubuntu-${FIRST}`],
['a distro bucket', 'distro', `-${FIRST}`]
])('keeps %s below a distro-root workspace folder spent', async (_case, side, bucket) => {
const homes = {
host: await mkdtemp(join(tmpdir(), 'orca-wsl-host-home-')),
distro: await mkdtemp(join(tmpdir(), 'orca-wsl-distro-home-'))
}
try {
await mkdir(join(homes[side], '.claude', 'projects', bucket), { recursive: true })
const retired = await discoverRetiredWorktreeNames({
workspaceRoots: ['\\\\wsl.localhost\\Ubuntu'],
home: homes.host,
env: {},
resolveWslHome: async () => homes.distro
})
expect(retired.names).toEqual(new Set([FIRST]))
} finally {
await rm(homes.host, { force: true, recursive: true })
await rm(homes.distro, { force: true, recursive: true })
}
})
it('reaches distro discovery from the real backfill, not only when called directly', async () => {
const distroHome = await mkdtemp(join(tmpdir(), 'orca-wsl-backfill-home-'))
try {
@@ -0,0 +1,64 @@
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { MARINE_CREATURES } from '../../../../shared/marine-creatures'
import { encodeClaudeProjectPath } from '../../../ai-vault/scanners/claude/claude-project-dir-encoding'
import { resetProjectDirCwdCacheForTests } from '../../../ai-vault/session-scanner-scope-discovery'
import { discoverRetiredWorktreeNames } from './worktree-retirement-discovery'
const FIRST = MARINE_CREATURES[0].toLowerCase()
describe('retirement discovery of Claude buckets', () => {
let home: string
beforeEach(async () => {
resetProjectDirCwdCacheForTests()
home = await mkdtemp(join(tmpdir(), 'orca-retire-claude-'))
})
afterEach(async () => {
await rm(home, { force: true, recursive: true })
})
// Claude Code cuts a long bucket name to `<first 200>-<hash>`; only the transcript cwd names the workspace.
async function addHashedBucket(cwd: string): Promise<void> {
const bucket = join(
home,
'.claude',
'projects',
`${encodeClaudeProjectPath(cwd).slice(0, 200)}-1x2y3z`
)
await mkdir(bucket, { recursive: true })
await writeFile(join(bucket, 'session.jsonl'), `${JSON.stringify({ type: 'user', cwd })}\n`)
}
it.each([
['the cut falls inside the workspace name', 195],
['the workspace root alone is longer than the cut', 230]
])('keeps a long workspace path spent when %s', async (_case, rootLength) => {
const root = `/synthetic/${'a'.repeat(rootLength - '/synthetic/'.length)}`
await addHashedBucket(`${root}/${FIRST}`)
const retired = await discoverRetiredWorktreeNames({ workspaceRoots: [root], home, env: {} })
expect(retired).toEqual({ names: new Set([FIRST]), complete: true })
})
it('does not credit a hashed bucket whose cwd is a sibling that encodes the same way', async () => {
const root = `/synthetic/${'a'.repeat(219)}`
await addHashedBucket(`${root}-${FIRST}`)
const retired = await discoverRetiredWorktreeNames({ workspaceRoots: [root], home, env: {} })
expect(retired.names).toEqual(new Set())
})
it('reads workspace names below a drive-root workspace folder', async () => {
await mkdir(join(home, '.claude', 'projects', `C--${FIRST}`), { recursive: true })
const retired = await discoverRetiredWorktreeNames({ workspaceRoots: ['C:\\'], home, env: {} })
expect(retired.names).toEqual(new Set([FIRST]))
})
})
@@ -2,10 +2,17 @@ import { claudeProfileHistoryDirs } from '../../../claude-accounts/claude-profil
import { homedir } from 'node:os'
import { join } from 'node:path'
import { isWslUncPath, parseWslUncPath } from '../../../../shared/wsl-paths'
import { relativePathInsideRoot } from '../../../../shared/cross-platform-path'
import {
encodeClaudeProjectPaths,
isClaudeProjectDirInScope
CLAUDE_BUCKET_NAME_MAX_LENGTH,
claudeProjectBucketNameBelowScope,
isClaudeProjectBucketInScope
} from '../../../ai-vault/scanners/claude/claude-project-dir-encoding'
import { CLAUDE_CWD_BUCKET_LAYOUT } from '../../../ai-vault/session-cwd-bucket-layouts'
import {
cachedProjectDirCwd,
cwdBucketScopePrefixes
} from '../../../ai-vault/session-scanner-scope-discovery'
import { wslGatedReaddir, wslGatedStat } from '../../../native-chat/wsl-transcript-fs-access'
import type { RetirementScanResult } from './worktree-retirement-backfill-scan'
import { normalizeRetirableGeneratedName } from './worktree-name-retirement'
@@ -29,21 +36,32 @@ export function collectRetiredNamesFromLeafNames(leafNames: Iterable<string>): S
/** Strip the encoded parent before extracting leaves; trailing-dash parsing can retire a numeric workspace's parent. */
export function extractBucketLeafCandidates(
bucketName: string,
encodedParents: readonly string[]
encodedParents: Iterable<string>
): string[] {
const bucket = bucketName.toLowerCase()
for (const parent of encodedParents) {
if (!parent || bucket === parent || !isClaudeProjectDirInScope(bucket, [parent])) {
continue
}
const remainder = bucket.slice(parent.length + 1)
// Every matching parent counts: a root parent (`-`) also prefixes the bucket of a longer one.
return [...encodedParents].flatMap((parent) => {
const remainder = claudeProjectBucketNameBelowScope(bucket, parent)
if (!remainder) {
continue
return []
}
const firstSegment = remainder.split('-')[0]
return remainder === firstSegment ? [remainder] : [remainder, firstSegment]
})
}
/** A `<first 200>-<hash>` bucket name has lost the workspace name; its transcript cwd still has it. */
async function hashedBucketLeafNames(
projectDir: string,
roots: readonly string[],
onRefusal: () => void
): Promise<string[]> {
const cwd = await cachedProjectDirCwd(projectDir, onRefusal, 'claude')
if (!cwd) {
return []
}
return []
// Compare real paths: /repo/my-app and /repo/my/app share a bucket name but not a cwd.
return roots.flatMap((root) => relativePathInsideRoot(root, cwd)?.split('/')[0] || [])
}
/** Share WSL scan admission/deadlines; report refusals without discarding names readable from other sources. */
@@ -95,14 +113,19 @@ function getClaudeProjectsDir(home: string, env: NodeJS.ProcessEnv): string {
type ClaudeProjectsSource = {
projectsDir: string
encodedParents: string[]
/** Workspace roots as this source's Claude records its cwd. */
roots: string[]
encodedParents: ReadonlySet<string>
}
// Fold both sides for case-insensitive filesystems; missed buckets risk reissuing used paths.
function encodeParents(paths: readonly string[]): string[] {
return paths
.filter((path) => path.length > 0)
.flatMap((path) => encodeClaudeProjectPaths(path).map((encoded) => encoded.toLowerCase()))
// Session History's bucket rules (long-path cut, roots, case, both WSL spellings); missed buckets risk reissuing used paths.
function claudeProjectsSource(projectsDir: string, paths: readonly string[]): ClaudeProjectsSource {
const roots = paths.filter((path) => path.length > 0)
return {
projectsDir,
roots,
encodedParents: cwdBucketScopePrefixes(CLAUDE_CWD_BUCKET_LAYOUT, roots)
}
}
/** WSL agents leave buckets in the distro home; only its default location is visible, not distro CLAUDE_CONFIG_DIR. */
@@ -114,13 +137,12 @@ async function claudeProjectsSources(args: {
}): Promise<{ sources: ClaudeProjectsSource[]; complete: boolean }> {
const sources: ClaudeProjectsSource[] = []
let complete = true
const hostParents = encodeParents(args.workspaceRoots)
if (hostParents.length > 0) {
if (args.workspaceRoots.some((root) => root.length > 0)) {
for (const projectsDir of new Set([
getClaudeProjectsDir(args.home ?? homedir(), args.env ?? process.env),
...claudeProfileHistoryDirs('projects')
])) {
sources.push({ projectsDir, encodedParents: hostParents })
sources.push(claudeProjectsSource(projectsDir, args.workspaceRoots))
}
}
const linuxRootsByDistro = new Map<string, string[]>()
@@ -137,10 +159,7 @@ async function claudeProjectsSources(args: {
for (const [distro, linuxRoots] of linuxRootsByDistro) {
const distroHome = await resolveWslHome(distro)
if (distroHome) {
sources.push({
projectsDir: join(distroHome, '.claude', 'projects'),
encodedParents: encodeParents(linuxRoots)
})
sources.push(claudeProjectsSource(join(distroHome, '.claude', 'projects'), linuxRoots))
continue
}
// Unresolved distro homes leave agent history unread, so discovery must remain retryable.
@@ -172,6 +191,15 @@ export async function discoverRetiredWorktreeNames(args: {
refused ||= listing.refused
for (const bucket of listing.names) {
leafNames.push(...extractBucketLeafCandidates(bucket, source.encodedParents))
if (
bucket.length > CLAUDE_BUCKET_NAME_MAX_LENGTH &&
isClaudeProjectBucketInScope(bucket.toLowerCase(), source.encodedParents)
) {
const projectDir = join(source.projectsDir, bucket)
leafNames.push(
...(await hashedBucketLeafNames(projectDir, source.roots, () => (refused = true)))
)
}
}
}