Make `xmd run` worktree paths readable

[taras]

Story

As someone using xmd run interactively, I want its managed worktrees to have short, readable paths, so I can enter them, inspect files, and continue working with ordinary filesystem tools.

Example

Given an ordinary run started in a repository named xmd-demo:

<Worktree name="task" branch="worktree-task">
 ```bash exec
 pwd

```

The worktree lives at and reports:

~/.xmd/worktrees/xmd-demo/task

Current gap

Ordinary xmd run currently places the same worktree under two full SHA-256 directory names and a final checkout directory:

~/.xmd/repositories/worktrees/ff326cec5b976a415f5dd20209cce334181533390b6655ec44df2d1ed8bfbfd1/86842adba411256398ba49ad04bf9070f3f558efd7a45ea1897ed1a3e78539b4/checkout

The first digest identifies the repository's canonical Git directory and the second identifies the authored worktree name. This protects provider-owned storage from collisions and path traversal, but it exposes an internal identity layout as the directory where a person is expected to work.

That tradeoff is appropriate for workflow-owned storage, which users do not navigate as an interactive checkout. It is a poor default for xmd run: ordinary managed worktrees deliberately survive the invocation because they contain work a person or Agent may continue afterward.

Contract

An ordinary xmd run worktree uses this readable common-path layout:

~/.xmd/worktrees/<repository>/<worktree>

For a root-level <Worktree> using the ambient repository, <repository> is a filesystem-safe form of the repository directory name. For a <Worktree> inside a lexical <Repository name="project">, it is a filesystem-safe form of that Repository name. <worktree> is a filesystem-safe form of the authored Worktree name.

Names remain labels, not path authority. No authored repository or worktree name can escape ~/.xmd/worktrees, select another checkout, or collide after filesystem case and normalization rules are applied. The original repository identity and Worktree name remain in trusted metadata and continue to decide compatibility and reuse.

The ordinary case stays simple. A short stable suffix is added only when two distinct identities would otherwise claim the same readable path, for example:

~/.xmd/worktrees/xmd-demo-ff326cec/task

Full identity digests may remain internal for metadata, locking, and collision proofs; they do not appear in the normal checkout path.

The readable directory is the checkout root. A captured <Worktree as="path" />, the contextual working directory inside a paired <Worktree>, and pwd all observe that path without an additional checkout segment.

Changing placement does not weaken the existing ordinary-run guarantees: managed worktrees persist across executions, compatible requests reuse them, conflicting identity or Git state refuses without mutation, and one invocation holds the same exclusive lock while using one.

Existing full-digest ordinary-run worktrees are not orphaned or duplicated. On compatible reuse, XMD makes the existing checkout available at its readable path without changing its branch, commits, index, working files, or Git worktree registration. If it cannot prove a safe transition—because the target conflicts, the checkout is active, or its identity is incompatible—it refuses actionably and leaves the existing worktree untouched.

Workflow-run Workspace paths and retained workflow identity do not change.

Acceptance

• A root-level <Worktree name="task"> started in xmd-demo uses ~/.xmd/worktrees/xmd-demo/task when that readable repository name is unclaimed.
• A Worktree inside <Repository name="project"> uses ~/.xmd/worktrees/project/<worktree> when that readable Repository name is unclaimed.
• The path returned through as, the contextual working directory, and pwd name the readable checkout root and contain neither full SHA-256 segments nor a trailing checkout segment in the common case.
• Repeating the same request reuses the same directory and preserves committed, staged, modified, and untracked work.
• Distinct repositories with the same readable name receive stable, distinguishable paths; the common path remains unsuffixed when no collision exists.
• Authored names containing traversal syntax or values that collide after filesystem normalization cannot escape the managed root or select another checkout.
• A compatible legacy full-digest worktree is reused at the readable path without data loss or duplicate Git registration.
• A conflicting or active legacy worktree refuses without moving, copying, resetting, or deleting it.
• Lock ownership and immutable creation-metadata checks continue to use the complete repository and Worktree identities rather than trusting readable directory names.
• Workflow-run worktree placement remains unchanged.
• architecture.md and the ordinary-run topology in specs/workflow-workspace-spec.md describe the readable interactive layout and its collision behavior.

Evidence

Run the focused ordinary-run placement and integration suites:

deno task test packages/workflow/tests/run-composition-managed.test.ts packages/workflow/tests/run-composition-ambient.test.ts packages/cli/tests/run-composition-deno.test.ts packages/cli/tests/run-composition-nested.test.ts

The regression evidence covers the simple ambient path, lexical Repository path, collisions, hostile names, persistent reuse, legacy adoption, active-use refusal, and the unchanged workflow boundary.

Related

• Add <Repository>, <Worktree>, <Issue>, and <PullRequest> to xmd run #643 introduced persistent managed Repository and Worktree composition under ordinary xmd run.