Enable users to spawn containers from anywhere on the fs

[nothingnesses]

Problem

Session/worktree mode requires all repositories to be under a single base_repo_dir. This is limiting because repositories are often spread across multiple locations and the requirement adds upfront configuration before the tool can be used. Making base_repo_dir accept an array of directories was considered, but rejected because different base directories can contain repos with the same directory name, leading to slug collisions and ambiguous workspace lookups. It would also increase lookup times proportionally to the number of directories added.

Workarounds don't hold up:

• --local mode bypasses the check, but loses worktree sandboxing.
• Setting base_repo_dir to a common ancestor like ~ slows discovery by scanning the entire home directory.
• Symlinking repos into base_repo_dir doesn't work, agent-box resolves symlinks to their real paths, which then fall outside base_repo_dir.

Proposal

Remove base_repo_dir entirely. ab new detects the git/jj root from the current directory (or an explicit path argument). Workspace paths use a content-addressable hash slug, the full 16 hex characters of a rapidhash u64 of the canonical repo path:

cd ~/anywhere/my-repo
ab new -s my-session --git
ab spawn -s my-session --git

# Workspace layout (before → after)
{workspace_dir}/git/{relative_path}/{session}     # old: requires base_repo_dir
{workspace_dir}/git/a1b2c3d4e5f6a7b8/{session}   # new: content-addressable slug

A .source-repo sentinel file inside each slug directory maps it back to the source repo's canonical path. This is the authoritative mapping, the hash is just a fast-path optimization for directory naming.

Why pure hex slugs (not name+hash)

A hybrid like my-repo-a1b2c3d4 was considered but rejected: repo directory names can contain non-UTF-8 bytes, characters invalid on other platforms, or sequences that complicate parsing (e.g., embedded hyphens conflicting with the name-hash separator). Pure hex avoids all sanitization edge cases. The sentinel file and ab info/ab dbg list provide human readability where needed.

Collision handling

16 hex chars = 64 bits gives a birthday-bound collision probability of ~50% at ~4 billion repos. On creation, if the computed slug already exists and its sentinel points to a different repo, ab new errors with a message naming both conflicting paths and suggests removing the conflicting workspace.

Sentinel file (.source-repo)

• Format: Canonical repo path followed by a trailing \n. Written atomically (temp file + rename).
• On creation (ab new): Compute slug → check sentinel → create or reuse. Before creating a new directory, scan existing slug dirs to prevent duplicate workspaces (e.g., after migration or hash algorithm change).
• On lookup (ab spawn): Compute slug → verify sentinel. If mismatched or absent, fall back to scanning all slug dirs. Found path is used directly (no automatic rename) to avoid breaking active sessions. Logs a suggestion to run ab dbg migrate.

Linked worktree resolution

Running ab new or ab spawn from inside a session workspace (which is a git linked worktree) now correctly resolves to the source repo root via repo.kind() + common_dir().parent(), instead of treating the worktree itself as a repo. Local mode (--local) preserves the current behavior of using the worktree directory as-is.

CLI changes

• ab new positional arg changes from a search string to a filesystem path. CWD detection is the primary workflow.
• ab spawn --repo changes from String to PathBuf.
• Fuzzy repo search (matching repos under base_repo_dir) is removed, users cd into the repo first or pass an explicit path.

New subcommands

• ab dbg list: Shows all workspaces with status (healthy/orphaned/old-layout), source path, slug, type, and session count. --orphans filters to broken workspaces. Accepts optional slug for detailed info.
• ab dbg migrate: Migrates old-layout workspaces to new slug format. Reads base_repo_dir from --base-repo-dir flag or config. Checks for active sessions (via *.lock files), supports --dry-run and --force. Idempotent and safe to re-run.
• ab dbg remap <old-path> <new-path>: Updates a workspace's sentinel after a repo move/rename. Renames slug directory if needed. Supports --dry-run.
• ab dbg remove: Enhanced with --orphans flag to clean up orphaned/old-layout workspaces. Supports --dry-run and --force.

Migration path

1. Recommended: Back up workspace_dir, run ab dbg migrate --dry-run to preview, then ab dbg migrate.
2. Alternative: Delete workspace_dir/git/ and workspace_dir/jj/ and recreate with ab new.

base_repo_dir becomes Option<PathBuf> with a deprecation warning. It's only needed for migration; after migrating, it can be removed from the config.

Repo move detection

When ab spawn can't find a workspace, it scans sentinels for orphans with a matching directory name and suggests ab dbg remap in the error message.

---

A detailed implementation plan covers all of the above, sentinel file semantics, migration safety, linked worktree handling, error messages, and dependency order, if ever it's decided that the proposal should be pursued.

[0xferrous]

My problem with content addressed hashes is that i cannot manually write a cd to go to a worktree of a given repo. And we cannot create a command like ab cd path that uses the hashing algo to generate the path and cd into since cd is not something we can do from within a process and have it change the cwd of the shell, it will require some form of shell integration and sourcing those into bash, zsh, nushell, etc.

I like the idea of solving moving of base repos not rendering existing worktrees/workspaces broken. I think best way to solve is to make the renames go through a special subcommand or explicit mapping from the user.

Also its confusing/inaccurate to call it a slug.

What is a slug?

A slug is a short, URL-friendly identifier made from a title or name.

Example:

• Title: What is a Slug?
• Slug: what-is-a-slug

Common properties of a slug:

• lowercase
• spaces replaced with -
• special characters removed
• easy to read

Used in URLs like:

• /blog/what-is-a-slug
• /users/john-doe

People also use “slug” more generally to mean a compact identifier for something, not just in URLs.

I am however open to make it easier for people to have multiple different base directories for git repos.

Setting base_repo_dir to a common ancestor like ~ slows discovery by scanning the entire home directory.

The repo discovery is only used as a convenience function to allow user to specify just the repo name as repo-id -r/--repository argument. We can instead add a new config repo_discovery_dirs which the user can set as an array of directories where it should search for repositories to solve the slow walking of the entirety of the home dir. This way we can still maintain a lot of simplicity that comes from a stable repo_id derived from a single base dir, not needing a hashing function and a result a shell integration for enabling cd-ing into worktrees.

Thoughts? I will continue thinking more on this in the meanwhile.

[0xferrous]

Opened #17 for separately tackling renames/moves

[nothingnesses]

Thanks for the thoughtful response. A few thoughts:

I agree that hex-only paths hurt host-side navigability, and that "slug" is the wrong term, I'll drop that language.

On repo_discovery_dirs, I think it solves the discovery problem well and makes sense as an improvement to discovery regardless of how the workspace path question is resolved. But the core issue remains: repos outside base_repo_dir still can't use session/worktree mode at all. calculate_relative_path() fails if the repo isn't under the configured base directory. repo_discovery_dirs addresses the -r convenience lookup, but not this.

On the cd concern, ab spawn handles working directory automatically, so this mainly affects host-side use cases like opening worktrees in an editor or browsing the workspace directory. Currently ls ~/.local/agent-box/workspaces/git/ gives a self-documenting view, and that would become opaque with hex hashes. That's a real cost, but ab info and the proposed ab dbg list would provide discoverability.

The property I was trying to achieve with the hash-based approach is that no repo-location configuration is needed. A user would cd into any repo on their system and ab new would just work, no base_repo_dir to set, no directory arrays to maintain. How would you solve multi-location repos without adding configuration overhead?

[0xferrous]

we conversed offline, the resolution here is:

1. add repo_discovery_dirs, add a --discovery-directory flag that can be specified multiple times to specify multiple of them, and have them merge with the one defined in the config. Use that for generating the list of dirs that the user is prompted with.
2. default the base_repo_dir's value to / so all paths on the system work.

[nothingnesses]

Here's a draft of the new implementation plan. I'll try and get it implemented so we can test to see if it'd work in practice.

Summary

base_repo_dir defaults to /

strip_prefix("/") produces the full absolute path as nested directories for workspace paths (e.g., {workspace_dir}/git/home/user/repos/myproject/session). No upfront config needed. Users who want shorter paths can still set base_repo_dir explicitly.

New repo_discovery_dirs config field

An array of paths that replaces scanning base_repo_dir for the -r flag. Validated at config load time to be mutually exclusive with an explicit non-/ base_repo_dir.

Linked worktree resolution

find_git_root() is refactored to detect linked worktrees via repo.kind() and resolve to the main repo root via common_dir(). This prevents ab new/ab spawn from inside a session workspace from treating the worktree as a separate repo. A separate find_git_workdir() preserves current behavior for --local mode.

Path canonicalization

All repo path computations canonicalize paths to prevent duplicate workspaces when accessing repos via symlinks.

ab dbg list

Scans workspace directories and shows status (healthy/unresolved), source path, type, and session count. ab dbg remove --unresolved cleans up workspaces whose source repo no longer exists.

ab new hint for bare names

When ab new my-project fails because my-project is not a valid path, the error suggests cd my-project && ab new or passing a full path.

Migration

Existing users with an explicit base_repo_dir are unaffected. Removing base_repo_dir from config causes old workspaces to become unresolved, surfaceable via ab dbg list --unresolved. Automated migration is deferred.

[0xferrous]

Linked worktree resolution

find_git_root() is refactored to detect linked worktrees via repo.kind() and resolve to the main repo root via common_dir(). This prevents ab new/ab spawn from inside a session workspace from treating the worktree as a separate repo. A separate find_git_workdir() preserves current behavior for --local mode.

this should be implemented for jj workspaces as well.

• add repo_discovery_dirs
• make --local work in workspaces/worktrees this already works
• add a command for changing base_workspace_dir

[0xferrous]

Please make separate PRs addressing each of the issues and let me know which you are taking up, I will assign and I can get on implementing the remainders.