Is repos_dir supported or vestigial

[blooop]

Question

Is repos_dir a supported configuration option, or is it vestigial?

Raised by #452, which found that deciding this collapses most of its second half either way, and that nothing user-facing documents the option at all: the README does not mention it, and docs/ has one incidental clause.

What it does today, undocumented:

• Moves --prune's entire scan root, its per-repo locks and its clone placement.
• Defeats the scratch-XDG_CACHE_HOME safety property for that root, which is the one hazard CLAUDE.md names as needing a config.toml most hosts do not have.
• Degrades four listing surfaces: a moved repos_dir makes dl --ls report devlaunch:false, unsaved:null and SIZE - for clones devlaunch itself made, so wf never cleans them.
• Leaves the one population on this map that is both unreclaimed and unnamed: clone trees under a repos_dir the config no longer names, where the metadata.json record survives as the only pointer because resolve_clone_path prefers a recorded path that is present.

So there are three honest answers, and picking one is worth more than leaving it ambiguous:

1. Supported — then it gets documented in the README and the docs/ page, the listing degradation is a bug to fix, and every reclaim path has to be correct under it.
2. Vestigial — then say so, and the listing degradation stops being a bug and becomes a documented consequence of an unsupported knob. Cheapest, and principle 2's "the user can see it" is satisfied by a sentence.
3. Removed — deleting beats adding (principle 3's simplicity clause). Establish first whether anything depends on it: the test suite scopes it (test/conftest.py), which is not the same as a user relying on it.

Note the interaction with this map: R1 in the map's Notes says a reclaim path's domain comes from cache_dir or the configured repos_dir. If repos_dir is vestigial or removed, R1 simplifies to one root, and several tickets get easier. That is a reason to decide it, not a reason to prejudge it.

How the answer gets tested: if supported, a test asserting --ls reports a moved-repos_dir clone as devlaunch's own. If vestigial or removed, the docs guard covers the sentence, and any test that scoped it is updated in the same change.

[blooop]

agent-decided (principle 3, simplicity: deleting beats adding): Removed. worktree.repos_dir comes out of config.toml, WorktreeConfig and the public surface. Not documented as supported, not kept as a named-but-unsupported knob. Nothing is moved on disk and nothing is deleted; the one thing a removal owes anybody is a line of output, and that is the whole migration.

1. What actually depends on it: nothing, and the record is unusually clean

Every route by which somebody could be relying on this was checked, and all of them come back empty.

• There is no writer, and there never was. config.rs's own module doc says it: "There is no writer -- nothing in devlaunch creates or edits this file". The Python original agrees (devlaunch/worktree/config.py at 1654daf^ had a to_dict, whose only callers were its own tests, and the Rust port dropped it for exactly that reason). So the only way this option is set is a human hand-authoring ~/.config/devlaunch/config.toml.
• Nothing user-facing has ever documented it. git log -S repos_dir -- README.md docs/ returns three commits and all three are the same aside, the one at docs/cleanup.md:86 about what --purge leaves. There has never been a "Configuration" section, a config.toml example, or a README row. The README's env-var table is the only knob table there is, and this is not in it.
• The spec that documented the backend this key belongs to did not offer it either. docs/worktree-backend-spec.md (deleted by Worktree-backend README section: delete or implement #306) had a ## Configuration section listing DEVLAUNCH_BACKEND, XDG_CACHE_HOME, --backend and --purge. Its answer for "override cache directory location" was XDG_CACHE_HOME. Even the aspirational document treated the env var as the supported mechanism and never mentioned the config key.
• No issue has ever asked for it. gh search issues repos_dir returns 15 issues; every one mentions it as an edge case something else has to survive (a purge blind spot, an owner column that reads -, a scratch-run hazard), never as a capability.
• No test exercises it. test/conftest.py scopes XDG_CONFIG_HOME in order to neutralise it -- its docstring says "config.toml can point repos_dir back at the real cache, which would defeat the isolation from the other direction" -- which is the suite defending against the option, not depending on it. test/fixtures/git_fixtures.py and test/e2e/test_full_workflow.py use a key named repos_dir for the default <cache>/repos path, unrelated to the config. The only test that ever sets a non-default value is the pure parse test in config.rs asserting "/custom/repos" round-trips, which tests the reader and no behaviour beyond it.

So this is precisely the ticket's distinction: a knob that exists because a port carried it over, not one anybody asked for. It arrived with the Python worktree backend, and #306 already deleted that backend's never-implemented documentation rather than implementing it. This is the same object under the same argument, one layer down.

And the capability is already provided, better, by something that is documented and tested. XDG_CACHE_HOME moves the clones, the bare caches, metadata.json, the completion cache and the tool verdicts together, and every surface respects it. repos_dir's only unique power is clones somewhere else from the rest of the cache, and the rest of the cache is bookkeeping measured in megabytes. There is no user need this serves that the env var does not serve without any of the consequences below.

2. What it breaks today: verified, and it is worse than "four degraded surfaces"

The --ls degradation is real, and the code says so in its own doc comments. is_devlaunch_clone (flows/listing.rs:398) is a containment test against cache_dir and nothing else:

WorkspaceSource::LocalFolder(path) => {
    let path = Path::new(path);
    path != cache_dir && path.starts_with(cache_dir)
}

A clone under a repos_dir outside the cache fails it, and because layout_of_clone is gated on the same answer, one predicate takes out devlaunch, disk, unsaved, the SIZE column and the picker's owner/repo/ref grouping together. Both is_devlaunch_clone's and owner_of's doc comments name the moved-repos_dir case as a known blind spot. wf reads devlaunch to decide which workspaces belong to finished work (docs/cleanup.md:594), so it never cleans them. Confirmed as #452 reported it.

The unreclaimed-and-unnamed population is real too, by the mechanism the ticket names. --prune scans clone_root = the current configured root (flows/lifecycle.rs:2122). A clone under a former root is outside that scan, so it is never a candidate; records_by_directory files its record under a path no candidate matches, so it is never classified; and records_for_absent_directories will not drop the record either, because resolve_clone_path returns the recorded path whenever it is absolute and present (flows/workspace_clone.rs:437-450) and present() says it is there. Nothing reclaims it, nothing names it, and metadata.json's record is the only pointer. Verified.

One thing #452 did not say, and it is the strongest fact on the ticket. The pointer is not stable either. A cold launch does not follow the record: prepare_workspace derives the directory from repos_dir via path_of (workspace_clone.rs:844), clones there if nothing is there, and then add_worktree inserts by (owner, repo, branch) -- overwriting local_path with the new root. So the sequence "clones under root A, root becomes B, relaunch cold" leaves the tree at A on disk with whatever is uncommitted in it, re-clones under B, and destroys the only pointer to A in the same write. That is not a hypothetical of removal. It is what this option does today to anyone who edits it, and it is why "vestigial" cannot be the answer.

And it is the one input that can break an invariant the code was written to protect. xdg.rs's module doc: three places used to spell the cache home out identically -- dl's own cache directory, the worktree config's default repos_dir, and metadata.json's default path -- "They have to agree because dl --purge reads the first to decide which workspaces are devlaunch's ... so a copy that drifted would make a purge silently stop recognising its own work." session.rs:63 and Records's doc comment repeat it. The port unified the default so the three cannot drift. repos_dir reintroduces the drift as a runtime input. Removing it is not a new invariant; it is finishing an existing one.

3. What removal costs, and why no migration beyond a notice

Nothing is deleted and nothing is moved. A clone tree under a configured repos_dir is untouched by this change: it stays exactly where its owner put it, uncommitted work included. Removal changes where dl looks, not what dl removes -- and --prune's root moving inwards, from a user-named tree to <cache>/repos, is the safe direction for a destructive command to move.

What removal does cost, for a user who has the key set, is the pointer. Their next cold launch of an affected workspace re-clones under <cache>/repos and overwrites local_path, and the old tree becomes a straggler nothing names. Note carefully that this is the same outcome the option already produces on any edit to it, and that the branch of it that touches work in the old tree is a stranding rather than a loss: the files are on disk, at a path the user chose and typed.

So the migration is one notice, and silence is the only thing that would be wrong. When config.toml names worktree.repos_dir and it resolves to anything other than <cache>/repos, dl says so once, on stderr, naming that directory: dl no longer reads this key, clones now live under <cache>/repos, move the old tree or point XDG_CACHE_HOME at its parent if you want them back.

• Not an error. config.rs's stated property is that a stale file is not punished -- a missing file is the defaults, an unknown key is ignored. Refusing to launch over a retired key would break that, over something that has destroyed nothing.
• But not silence either, and this is where the auto_fetch precedent stops applying. That precedent covers a key "retired without ever gating anything". repos_dir gated where the clones went. A key with authority, retired in silence, is precisely how a tree ends up unfindable. One line is the difference, and it costs a notice arm.
• Explicitly not: moving anything. Auto-relocating a clone tree means a bulk move of hardlink-shared trees across a possible filesystem boundary while containers may be bind-mounting them. That is far more dangerous than the straggler it would tidy, and it is a delete-and-recreate wearing a migration's clothes. Refused under principle 1.

Principle 1 is satisfied without an explicit human answer here because nothing is removed. Principle 2 is satisfied by the notice, which is the same "the user can see it and decide" trade #461 is built on.

4. Why not the other two answers

Supported is refused on cost against nothing. It buys a capability XDG_CACHE_HOME already provides, and it charges: a README row and a docs section for a knob with no writer; splitting is_devlaunch_clone into an ownership predicate and a provenance predicate, which is the second answer to one question that layout_of_clone's doc comment exists to say the code deliberately keeps as one (devlaunch#165, then #171 were both that shape); every reclaim path on this map correct under two roots forever; and the config.toml scratch-cache hazard promoted from an accident to a supported behaviour that CLAUDE.md and conftest.py have to keep defending against. Documenting it would also mean documenting §2's overwrite: "changing this key strands your clones and drops the record". An option whose honest documentation is a warning is not an option.

Vestigial is refused because it is incoherent, not because it is cheap. It would leave a knob with no obligation to be correct and full authority over a destructive command's scan root, its locks and its clone placement. "Unsupported, and it still decides what --prune deletes" is not a contract anyone can act on, and it leaves §2's record-overwrite in the build as a documented consequence of a knob we have declined to stand behind. It also leaves R1 two-rooted, so the map pays the two-root cost anyway and gets a sentence for it. This is the map's own precedent applied one level up: PrunePlan's doc comment says a plan and the outcome that acts on it must not be able to disagree; a knob we do not support and do not obey either is the same disagreement in the configuration.

5. What removal buys

• R1 collapses to one root. With repos_dir gone, clone_root is <cache>/repos by construction, so "enumerated from cache_dir or from the configured repos_dir" becomes "enumerated from cache_dir". R2 is unaffected and still worth keeping: a printed root is good practice regardless of how many roots there are.
• The --ls degradation becomes unrepresentable rather than fixed. Every clone dl makes is inside cache_dir, so the single containment test is complete and devlaunch:false / SIZE - / unsaved:null for one of dl's own clones has no way to occur. That is a deletion doing what a second predicate was going to be asked to do. (It is complete for a given cache home: a moved XDG_CACHE_HOME still strands what the old one held, the same way it does for every XDG-respecting tool, and that is not this key's doing.)
• The scratch-cache safety property becomes whole. XDG_CACHE_HOME=/tmp/... dl-next ... scopes everything, with no config.toml caveat. CLAUDE.md's trade-off paragraph shrinks to one variable with no hazard behind it, and conftest.py keeps scoping XDG_CONFIG_HOME as harmless belt-and-braces rather than as a load-bearing guard.
• Real deletion, not just a smaller struct. expand_tilde and is_ours_to_create lose their only callers; ensure_repos_dir goes with them, which makes worktree_config() pure (it currently creates a directory as a side effect of loading, and RepositoryManager::new already creates the same directory at repo_manager.rs:1043). Four tests in config.rs go with the functions they pin.
• No promised-API break. WorktreeConfig::repos_dir is in public-api.rest.txt (line 298), the binary surface, not public-api.api.txt. wf is not entitled to it. The snapshot is regenerated by scripts/public-api-snapshots.sh in the same change.

6. Build work this implies

Named rather than ticketed, per the map's convention. This is one small PR, not a ticket of its own unless the map wants it visible.

1. Drop repos_dir from StoredWorktree and WorktreeConfig; delete expand_tilde, is_ours_to_create, ensure_repos_dir and their tests. WorkspaceCloneManager::from_config takes the cache-derived root plus fetch_interval; clone_root reads the manager as it does now, so lifecycle.rs needs no change beyond its doc comment, which currently explains a config.toml that can no longer move anything.
2. One notice arm: config.toml names worktree.repos_dir and it is not <cache>/repos -> one stderr line naming the directory and XDG_CACHE_HOME. Red first: a config naming a root, and the notice as the assertion.
3. Regenerate both public-API snapshots via scripts/public-api-snapshots.sh.
4. Docs: docs/cleanup.md:86's clause loses its config.toml sentence, and the purge's "leaving" paragraph loses that third case (--purge still leaves dl <path> and dl <git-url> workspaces, which is Clones outside repos_dir and dl path or url workspaces #452's answer and unchanged). docs/rust-rewrite-plan.md row 9 is archival and stays as written; it records a port that happened.
5. #461 is unblocked as written, and slightly smaller: its first bullet drops "which is devlaunch's own under a moved repos_dir" from the list of things a user cannot tell apart, because there is no such workspace any more. The --ls degradation it deferred to this ticket needs no build work at all -- step 1 removes the case.
6. #455's table loses two of the three "left standing" rows Clones outside repos_dir and dl path or url workspaces #452 specified: clones under a repos_dir outside the cache, and clones under a former one. What replaces them is one row for the retired key: an old tree is left where its owner put it, named once by the notice, reclaimed by nothing, and rm -rf is the answer. The .bare-caches row goes with them.

How it is tested. The notice, red first, as above. The config.rs test asserting "/custom/repos" parses is deleted rather than updated -- it pins the reader for a key that no longer exists. test_docs_prose.py and test_readme_cli_doc.py are unaffected (no flag changes). Nothing else in the suite sets the key, which is §1's point restated as a diff: removal touches no test that was testing behaviour.

Fog, and one adjacent finding worth the map's attention

Four of the six keys in config.toml are parsed and never consumed. enabled, cleanup.auto_prune, cleanup.prune_after_days and fallback_image are read into WorktreeConfig, defaulted, unit-tested, published on the binary API surface, and read by nothing outside config.rs. fetch_interval and repos_dir are the only two anything uses. With repos_dir gone, config.toml is a file with one live knob and four dead ones, none of them documented, with no writer.

That makes "should config.toml exist at all" a real question rather than a rhetorical one, and it is the same question this ticket just answered about one key. It is out of scope here and not ticketed: auto_prune and prune_after_days are the interesting pair, because a --prune age threshold is a knob this map's destination might actually want, and deciding their fate before the prune unit is decided would be guessing. Recorded so the map owns it rather than rediscovering it. enabled and fallback_image are the least defensible of the four: they are the Python worktree backend's on/off switch and its image-for-a-repo-with-no-devcontainer, carried over by the port, and nothing in the Rust tree has ever had a fallback-image mechanism for the second to feed.