workforest 0.2.3__tar.gz → 0.3.0__tar.gz

workforest-0.3.0/.claude/rules/architecture.md

@@ -0,0 +1,16 @@
+# Architecture invariants
+
+- `gitutil.py` is the only module that spawns git. Consumers get typed
+  results; worktree data comes from `--porcelain -z` output, never from
+  parsing the human-readable form.
+- `cli.py` is the sole stdout writer. Commands return
+  `ShellAction | str | None`; stdout carries the shell-wrapper cd protocol,
+  so nothing else may print there (hook/script stdout is diverted to stderr).
+- `tui.py`: everything except the fzf subprocess is pure and unit-tested;
+  fzf is the only sanctioned external tool there.
+- `completions.py` must never break the shell: any error yields an empty
+  candidate list, and output stays plain `NAME<TAB>ANNOTATION` lines.
+- `integrations/claude.py` is experimental: it reads Claude Code's private
+  on-disk state. Session lines are rewritten by JSON parsing, never by
+  string substitution.
+- README.md is the project reference; there is no separate design document.

workforest-0.3.0/.claude/rules/conventions.md

@@ -0,0 +1,12 @@
+# Code conventions
+
+- Python 3.14, uv-managed. Verify changes with `make check` (ruff lint +
+  format check, mypy, pytest with a 90% coverage floor). Run
+  `uv run ruff format .` rather than hand-formatting.
+- When a return value or constant bundles fields whose positions carry
+  meaning, use a small named dataclass — `@dataclass(slots=True,
+  frozen=True)` — not an anonymous tuple or nested dict. Plain dicts are for
+  genuine key→value lookups only (env maps, branch→remotes).
+- Pre-1.0 with zero users: on breaking changes keep the clean design and
+  state what to re-run (e.g. re-eval shell-init). Never add
+  backward-compatibility shims.

workforest-0.3.0/.claude/rules/tests.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "tests/**/*.py"
+---
+
+# Test conventions
+
+- Isolation contract (see `tests/conftest.py`): no test may read or write
+  the real environment. The autouse `isolated_env` fixture redirects HOME,
+  XDG_CONFIG_HOME, and git config, and pins SHELL=/bin/sh, EDITOR, and
+  NO_COLOR — rely on it instead of patching these per test.
+- Build repos through the `repo` / `make_repo` fixtures and the `Repo`
+  helper methods (`add_branch`, `add_remote`, `write_project_config`,
+  `make_dirty`) rather than raw git calls.
+- Coverage floor is 90% (`--cov-fail-under=90` in pyproject.toml); pure
+  helpers are expected to be unit-tested, subprocess/terminal glue may be
+  `# pragma: no cover`.

{workforest-0.2.3 → workforest-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workforest
-Version: 0.2.3
+Version: 0.3.0
 Summary: Git worktree forest management: create, open, and clean up per-branch worktrees with project-defined setup hooks
 Project-URL: Homepage, https://github.com/ArkadyBuryakov/workforest
 Author-email: Arkady Buryakov <arkady@buryakov.pro>
@@ -20,6 +20,14 @@ Description-Content-Type: text/markdown
 
 # Workforest
 
+## Elevator pitch
+
+Your repo has one working directory; your AI agents want five. Workforest
+gives every feature — and every agent — its own disposable git worktree, so
+parallel work on the same repo never collides.
+
+## About
+
 Git worktree forest management: one main checkout plus any number of
 disposable, per-branch worktrees in a predictable location — created, set up,
 opened, and cleaned up with one command.
@@ -108,17 +116,17 @@ All keys, with defaults:
 ```yaml
 worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"  # where the forest lives
 opener: ""              # default opener; "" → $VISUAL → $EDITOR
-openers: {}             # name -> command template, e.g. edit: "$EDITOR {target}"
-window_command: ""      # "" → current shell; or e.g.
-                        # "kitty --title {title} --directory {worktree} $WF_COMMAND"
+openers: {}             # name -> shell command, e.g. edit: '$EDITOR "$WF_TARGET"'
+window_command: ""      # "" → current shell; or e.g. kitty --title "$WF_TITLE"
+                        #   --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
 scripts: {}             # name -> snippet for `wf run NAME`
 ```
 
-Openers and `window_command` are command templates sharing one variable
-family, which the launched process (and every script) also receives as
-environment variables:
+Openers and `window_command` are plain shell commands, run via `$SHELL -c`
+with one variable family in the environment — the same family the launched
+process and every script receive:
 
 | Variable | Value |
 |---|---|
@@ -130,15 +138,17 @@ environment variables:
 | `WF_TARGET` | the `-p` argument, default `.` (launch-only) |
 | `WF_TITLE` | window label, `project_name: feat-x` (launch-only) |
 
-In templates, `$WF_X` (like any `$ENV` variable) inserts raw text that
-word-splits into multiple arguments, while `{x}` — `{worktree}`, `{target}`,
-`{title}`, … — inserts the shell-quoted value as exactly one argument.
-Openers run with the worktree root as working directory; in
-`window_command` the resolved opener command is additionally available as
-`$WF_COMMAND` (spliced into argv words) or `{command}` (one argument, for
-`$SHELL -c` wrappers). Spawned windows shed activation state inherited from
-the invoking shell (Python venv, conda, nvm, rvm) so the new session starts
-clean instead of carrying an environment it cannot deactivate.
+Standard shell rules apply — there is no workforest template syntax:
+`"$WF_X"` is exactly one argument, bare `$WF_X` word-splits, and `$$`,
+braces, pipes, and `&&` mean whatever your shell says they mean (a
+misspelled `$WF_VAR` expands to empty, as in any shell). Openers run with
+the worktree root as working directory. In `window_command` the resolved
+opener command is additionally available as `$WF_COMMAND` — still
+unexpanded, so run it through a shell of its own for its `$WF_*` references
+to resolve: `$SHELL -c "$WF_COMMAND"`. Spawned windows shed activation
+state inherited from the invoking shell (Python venv, conda, nvm, rvm) so
+the new session starts clean instead of carrying an environment it cannot
+deactivate.
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
@@ -187,8 +197,23 @@ workforest tui    [MODE]
 workforest init   [--local]
 workforest config [--json]
 workforest shell-init [bash|zsh]
+workforest claude copy-session SESSION_ID   # experimental
 ```
 
+`open` (and the opener shortcut, e.g. `wf edit`) without NAME opens the
+worktree you are standing in.
+
+`create` resolves BRANCH in order: existing local branch, then a branch on
+exactly one remote (checked out tracking it), then a brand-new branch.
+`REMOTE/BRANCH` picks the remote explicitly — needed when several remotes
+carry the same branch name; if that local name is already taken, `create`
+prompts for a different one.
+
+`workforest claude` (shown only when `~/.claude` exists) copies a Claude
+Code session from the main worktree into the current one. It is
+**experimental**: it manipulates Claude Code's private on-disk state,
+which is not a stable interface, so any Claude Code update may break it.
+
 Exit codes: `0` ok · `1` error · `2` usage · `3` cancelled · `4` config error.
 Human messages go to stderr; stdout carries only machine output (`cd`
 directives for the `wf` wrapper, `--porcelain` listings, dumps).

{workforest-0.2.3 → workforest-0.3.0}/README.md

@@ -1,5 +1,13 @@
 # Workforest
 
+## Elevator pitch
+
+Your repo has one working directory; your AI agents want five. Workforest
+gives every feature — and every agent — its own disposable git worktree, so
+parallel work on the same repo never collides.
+
+## About
+
 Git worktree forest management: one main checkout plus any number of
 disposable, per-branch worktrees in a predictable location — created, set up,
 opened, and cleaned up with one command.
@@ -88,17 +96,17 @@ All keys, with defaults:
 ```yaml
 worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"  # where the forest lives
 opener: ""              # default opener; "" → $VISUAL → $EDITOR
-openers: {}             # name -> command template, e.g. edit: "$EDITOR {target}"
-window_command: ""      # "" → current shell; or e.g.
-                        # "kitty --title {title} --directory {worktree} $WF_COMMAND"
+openers: {}             # name -> shell command, e.g. edit: '$EDITOR "$WF_TARGET"'
+window_command: ""      # "" → current shell; or e.g. kitty --title "$WF_TITLE"
+                        #   --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
 scripts: {}             # name -> snippet for `wf run NAME`
 ```
 
-Openers and `window_command` are command templates sharing one variable
-family, which the launched process (and every script) also receives as
-environment variables:
+Openers and `window_command` are plain shell commands, run via `$SHELL -c`
+with one variable family in the environment — the same family the launched
+process and every script receive:
 
 | Variable | Value |
 |---|---|
@@ -110,15 +118,17 @@ environment variables:
 | `WF_TARGET` | the `-p` argument, default `.` (launch-only) |
 | `WF_TITLE` | window label, `project_name: feat-x` (launch-only) |
 
-In templates, `$WF_X` (like any `$ENV` variable) inserts raw text that
-word-splits into multiple arguments, while `{x}` — `{worktree}`, `{target}`,
-`{title}`, … — inserts the shell-quoted value as exactly one argument.
-Openers run with the worktree root as working directory; in
-`window_command` the resolved opener command is additionally available as
-`$WF_COMMAND` (spliced into argv words) or `{command}` (one argument, for
-`$SHELL -c` wrappers). Spawned windows shed activation state inherited from
-the invoking shell (Python venv, conda, nvm, rvm) so the new session starts
-clean instead of carrying an environment it cannot deactivate.
+Standard shell rules apply — there is no workforest template syntax:
+`"$WF_X"` is exactly one argument, bare `$WF_X` word-splits, and `$$`,
+braces, pipes, and `&&` mean whatever your shell says they mean (a
+misspelled `$WF_VAR` expands to empty, as in any shell). Openers run with
+the worktree root as working directory. In `window_command` the resolved
+opener command is additionally available as `$WF_COMMAND` — still
+unexpanded, so run it through a shell of its own for its `$WF_*` references
+to resolve: `$SHELL -c "$WF_COMMAND"`. Spawned windows shed activation
+state inherited from the invoking shell (Python venv, conda, nvm, rvm) so
+the new session starts clean instead of carrying an environment it cannot
+deactivate.
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
@@ -167,8 +177,23 @@ workforest tui    [MODE]
 workforest init   [--local]
 workforest config [--json]
 workforest shell-init [bash|zsh]
+workforest claude copy-session SESSION_ID   # experimental
 ```
 
+`open` (and the opener shortcut, e.g. `wf edit`) without NAME opens the
+worktree you are standing in.
+
+`create` resolves BRANCH in order: existing local branch, then a branch on
+exactly one remote (checked out tracking it), then a brand-new branch.
+`REMOTE/BRANCH` picks the remote explicitly — needed when several remotes
+carry the same branch name; if that local name is already taken, `create`
+prompts for a different one.
+
+`workforest claude` (shown only when `~/.claude` exists) copies a Claude
+Code session from the main worktree into the current one. It is
+**experimental**: it manipulates Claude Code's private on-disk state,
+which is not a stable interface, so any Claude Code update may break it.
+
 Exit codes: `0` ok · `1` error · `2` usage · `3` cancelled · `4` config error.
 Human messages go to stderr; stdout carries only machine output (`cd`
 directives for the `wf` wrapper, `--porcelain` listings, dumps).

workforest-0.3.0/completions/_workforest

@@ -0,0 +1,44 @@
+#compdef workforest wf
+# zsh completion for workforest / wf — installed to zsh site-functions.
+# Dynamic candidates are delegated to `workforest --complete TOPIC`.
+
+local topic cmd line name rest kind desc
+local -a items cmds
+cmd="${words[2]:-}"
+if (( CURRENT == 2 )); then
+    topic=commands
+else
+    case "$cmd" in
+        create) topic=branches ;;
+        open|delete|checkout) topic=worktrees ;;
+        run) topic=scripts ;;
+        claude) topic=claude-sessions ;;
+        tui|list|init|config|shell-init) topic=none ;;
+        *) topic=worktrees ;;
+    esac
+fi
+if [[ "$topic" != none ]]; then
+    items=(${(f)"$(workforest --complete "$topic" 2>/dev/null)"})
+    if [[ "$topic" == commands ]]; then
+        # NAME<TAB>KIND<TAB>DESCRIPTION → described candidates; one group
+        # (kind spelled out in the description) so list order, alignment,
+        # and the command/opener distinction survive fzf-tab's merging.
+        # Cyan for openers, but only under fzf-tab (fzf renders ANSI with
+        # --ansi; plain complist would print the escapes literally).
+        local pre="" post=""
+        if (( ${+functions[fzf-tab-complete]} )); then
+            pre=$'\e[36m' post=$'\e[0m'
+        fi
+        for line in "${items[@]}"; do
+            name="${line%%$'\t'*}"
+            rest="${line#*$'\t'}"
+            kind="${rest%%$'\t'*}"
+            desc="${rest#*$'\t'}"
+            [[ "$kind" == opener ]] && desc="${pre}opener: ${desc}${post}"
+            cmds+=("${name//:/\\:}:${desc}")
+        done
+        (( ${#cmds} )) && _describe -t commands 'workforest command' cmds
+    else
+        (( ${#items} )) && compadd -a items
+    fi
+fi

{workforest-0.2.3 → workforest-0.3.0}/src/workforest/__init__.py

@@ -1,3 +1,3 @@
 """Workforest — git worktree forest management."""
 
-__version__ = "0.2.3"
+__version__ = "0.3.0"

{workforest-0.2.3 → workforest-0.3.0}/src/workforest/cli.py

@@ -1,35 +1,44 @@
 """argparse front-end: shortcut dispatch, error → exit-code mapping, and the
-sole writer to stdout (DESIGN §3.3/§5)."""
+sole writer to stdout."""
 
 import argparse
 import os
+import signal
 import sys
 from pathlib import Path
 from typing import Any
 
 from workforest import __version__, commands, output
 from workforest.commands import CommandResult
-from workforest.errors import EXIT_CANCELLED, EXIT_OK, WorkforestError
+from workforest.errors import EXIT_OK, WorkforestError
 from workforest.launch import ShellAction
 
-SUBCOMMANDS = frozenset(
-    {
-        "create",
-        "open",
-        "list",
-        "delete",
-        "checkout",
-        "run",
-        "tui",
-        "init",
-        "config",
-        "shell-init",
-    }
-)
+# Single source for subcommand names and their one-line help: build_parser()
+# and the `commands` completion topic both read from here.
+SUBCOMMAND_HELP: dict[str, str] = {
+    "create": "create (or reuse) a worktree for a branch and open it",
+    "open": "open an existing worktree",
+    "list": "list managed worktrees",
+    "delete": "delete worktree(s)",
+    "checkout": "delete a worktree and check its branch out in main",
+    "run": "run a named script from the merged config",
+    "tui": "interactive mode (requires fzf)",
+    "init": "scaffold a .workforest.yaml project config",
+    "config": "show the merged configuration and its sources",
+    "shell-init": "print the wf shell wrapper (eval in your shell rc)",
+    "claude": "Claude Code integration (experimental: may break on any Claude Code update)",
+}
+
+SUBCOMMANDS = frozenset(SUBCOMMAND_HELP) - {"claude"}  # claude is feature-gated
+
+# Marks a stdout line as a directive for the wf shell wrapper to eval. The
+# unit-separator control byte cannot appear in data output (listings, dumps),
+# so the wrapper never mistakes data for something to execute.
+SHELL_DIRECTIVE_PREFIX = "\x1f"
 
 
 def _claude_available() -> bool:
-    """Feature gate (DESIGN §3.7): the integration is invisible without
+    """Feature gate: the integration is invisible without
     ~/.claude. Filesystem check only — core never imports the integration."""
     return (Path.home() / ".claude").is_dir()
 
@@ -43,7 +52,7 @@ def _known_subcommands() -> frozenset[str]:
 def _emit(result: CommandResult) -> None:
     match result:
         case ShellAction(script=script):
-            print(script)
+            print(f"{SHELL_DIRECTIVE_PREFIX}{script}")
         case str() as text if text:
             print(text)
         case _:
@@ -139,28 +148,30 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", required=True)
 
     def opener_args(p: argparse.ArgumentParser) -> None:
-        p.add_argument("-o", "--opener", help="opener name or command template")
+        p.add_argument("-o", "--opener", help="opener name or shell command")
         p.add_argument(
-            "-p", "--path", help="path inside the worktree, passed to the opener as {target}"
+            "-p", "--path", help="path inside the worktree, passed to the opener as $WF_TARGET"
         )
 
-    p = sub.add_parser("create", help="create (or reuse) a worktree for a branch and open it")
-    p.add_argument("branch", nargs="?", help="branch name (default: current branch)")
+    p = sub.add_parser("create", help=SUBCOMMAND_HELP["create"])
+    p.add_argument(
+        "branch", nargs="?", help="branch name or REMOTE/BRANCH (default: current branch)"
+    )
     opener_args(p)
     p.add_argument("--no-hooks", action="store_true", help="skip symlinks and setup scripts")
     p.add_argument("--no-open", action="store_true", help="create only, do not open")
     p.set_defaults(func=_handle_create)
 
-    p = sub.add_parser("open", help="open an existing worktree")
+    p = sub.add_parser("open", help=SUBCOMMAND_HELP["open"])
     p.add_argument("name", nargs="?", help="worktree directory name")
     opener_args(p)
     p.set_defaults(func=_handle_open)
 
-    p = sub.add_parser("list", help="list managed worktrees")
+    p = sub.add_parser("list", help=SUBCOMMAND_HELP["list"])
     p.add_argument("--porcelain", action="store_true", help="stable tab-separated output")
     p.set_defaults(func=_handle_list)
 
-    p = sub.add_parser("delete", help="delete worktree(s)")
+    p = sub.add_parser("delete", help=SUBCOMMAND_HELP["delete"])
     p.add_argument("names", nargs="+", metavar="NAME")
     p.add_argument("--force", action="store_true", help="skip the dirty-worktree confirmation")
     group = p.add_mutually_exclusive_group()
@@ -168,12 +179,12 @@ def build_parser() -> argparse.ArgumentParser:
     group.add_argument("--keep-branch", action="store_true", help="never delete the branch")
     p.set_defaults(func=_handle_delete)
 
-    p = sub.add_parser("checkout", help="delete a worktree and check its branch out in main")
+    p = sub.add_parser("checkout", help=SUBCOMMAND_HELP["checkout"])
     p.add_argument("name", metavar="NAME")
     p.add_argument("--force", action="store_true", help="skip the dirty-worktree confirmation")
     p.set_defaults(func=_handle_checkout)
 
-    p = sub.add_parser("run", help="run a named script from the merged config")
+    p = sub.add_parser("run", help=SUBCOMMAND_HELP["run"])
     p.add_argument("script", metavar="SCRIPT")
     p.add_argument(
         "args",
@@ -183,7 +194,7 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p.set_defaults(func=_handle_run)
 
-    p = sub.add_parser("init", help="scaffold a .workforest.yaml project config")
+    p = sub.add_parser("init", help=SUBCOMMAND_HELP["init"])
     p.add_argument(
         "--local",
         action="store_true",
@@ -191,20 +202,20 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p.set_defaults(func=_handle_init)
 
-    p = sub.add_parser("config", help="show the merged configuration and its sources")
+    p = sub.add_parser("config", help=SUBCOMMAND_HELP["config"])
     p.add_argument("--json", action="store_true")
     p.set_defaults(func=_handle_config)
 
-    p = sub.add_parser("shell-init", help="print the wf shell wrapper (eval in your shell rc)")
+    p = sub.add_parser("shell-init", help=SUBCOMMAND_HELP["shell-init"])
     p.add_argument("shell", nargs="?", choices=("bash", "zsh"), help="default: from $SHELL")
     p.set_defaults(func=_handle_shell_init)
 
-    p = sub.add_parser("tui", help="interactive mode (requires fzf)")
+    p = sub.add_parser("tui", help=SUBCOMMAND_HELP["tui"])
     p.add_argument("mode", nargs="?", help="initial mode (create/open/checkout/delete)")
     p.set_defaults(func=_handle_tui)
 
     if _claude_available():
-        p = sub.add_parser("claude", help="Claude Code integration")
+        p = sub.add_parser("claude", help=SUBCOMMAND_HELP["claude"])
         claude_sub = p.add_subparsers(dest="claude_command", required=True)
         cp = claude_sub.add_parser(
             "copy-session", help="copy a session from the main worktree into this one"
@@ -251,6 +262,12 @@ def main(argv: list[str] | None = None) -> int:
             raise
         output.error(str(exc))
         return exc.exit_code
-    except KeyboardInterrupt:
+    except KeyboardInterrupt:  # pragma: no cover - terminates the process
+        # Die by SIGINT instead of exiting normally: a parent shell decides
+        # whether to abort a loop by how the child died (WIFSIGNALED), not by
+        # its exit code. Explicit prompt cancels still exit EXIT_CANCELLED.
         output.info("")
-        return EXIT_CANCELLED
+        sys.stderr.flush()
+        signal.signal(signal.SIGINT, signal.SIG_DFL)
+        os.kill(os.getpid(), signal.SIGINT)
+        return 128 + signal.SIGINT  # not reached

{workforest-0.2.3 → workforest-0.3.0}/src/workforest/commands.py

@@ -1,8 +1,9 @@
 """Core commands. Each returns a ShellAction (stdout directive), a str
-(stdout text), or None — cli.py is the sole stdout writer (DESIGN §5)."""
+(stdout text), or None — cli.py is the sole stdout writer."""
 
 import importlib.resources
 import json
+from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -42,8 +43,8 @@ def build_context(cwd: Path | None = None) -> Context:
 
 
 def managed_worktrees(ctx: Context) -> list[gitutil.Worktree]:
-    """Worktrees located directly inside the resolved worktrees dir
-    (DESIGN §3.5) — the only ones we list, complete, or delete."""
+    """Worktrees located directly inside the resolved worktrees dir —
+    the only ones we list, complete, or delete."""
     return [
         worktree
         for worktree in gitutil.list_worktrees(ctx.main)
@@ -62,6 +63,47 @@ def short_branch_name(branch: str) -> str:
     return branch.rsplit("/", 1)[-1]
 
 
+@dataclass(slots=True, frozen=True)
+class ResolvedBranch:
+    branch: str  # local branch name
+    track: str | None  # remote ref the branch should track, if any
+
+
+def _resolve_branch(ctx: Context, spec: str) -> ResolvedBranch:
+    """Resolve BRANCH or REMOTE/BRANCH to a local branch and its remote ref.
+
+    Precedence: exact local branch, explicit REMOTE/BRANCH, a branch known to
+    exactly one remote; anything else names a new local branch.
+    """
+    if gitutil.branch_exists(spec, ctx.main):
+        return ResolvedBranch(spec, track=None)
+    remote_map = gitutil.remote_branches(ctx.main)
+    for remote in sorted(gitutil.remotes(ctx.main), key=len, reverse=True):
+        branch = spec.removeprefix(f"{remote}/")
+        if branch == spec:
+            continue
+        if remote not in remote_map.get(branch, ()):
+            raise WorkforestError(f"branch {branch!r} not found on remote {remote!r}")
+        while gitutil.branch_exists(branch, ctx.main):
+            # The obvious local name is taken (possibly tracking a different
+            # remote), so the new branch needs a name of its own.
+            if not output.interactive():
+                raise WorkforestError(
+                    f"branch {branch!r} already exists locally; `wf create {branch}` to use it"
+                )
+            branch = output.ask(f"branch {branch!r} already exists locally; local name for {spec}:")
+            if not branch:
+                raise CancelledError("cancelled")
+        return ResolvedBranch(branch, track=spec)
+    carriers = remote_map.get(spec, [])
+    if len(carriers) > 1:
+        raise WorkforestError(
+            f"branch {spec!r} exists on multiple remotes ({', '.join(carriers)}); "
+            f"pick one, e.g. `wf create {carriers[0]}/{spec}`"
+        )
+    return ResolvedBranch(spec, track=f"{carriers[0]}/{spec}" if carriers else None)
+
+
 def _script_env(ctx: Context, worktree: Path, branch: str | None) -> dict[str, str]:
     return hooks.script_env(
         main=ctx.main,
@@ -84,6 +126,8 @@ def cmd_create(
         branch = gitutil.current_branch(ctx.cwd_root)
         if branch == "HEAD":
             raise WorkforestError("detached HEAD: specify a branch name")
+    resolved = _resolve_branch(ctx, branch)
+    branch = resolved.branch
 
     existing = gitutil.find_branch_worktree(branch, ctx.main)
     if existing is not None:
@@ -102,7 +146,7 @@ def cmd_create(
         if worktree_path.exists():
             raise WorkforestError(f"directory exists but is not a worktree: {worktree_path}")
         ctx.worktrees_dir.mkdir(parents=True, exist_ok=True)
-        gitutil.worktree_add(ctx.main, worktree_path, branch)
+        gitutil.worktree_add(ctx.main, worktree_path, branch, track=resolved.track)
         output.success(f"created worktree for {branch!r} at {worktree_path}")
         if not no_hooks:
             env = _script_env(ctx, worktree_path, branch)
@@ -131,9 +175,14 @@ def cmd_open(
     opener: str | None = None,
     path_arg: str | None = None,
 ) -> CommandResult:
-    if not name:
-        raise UsageError("worktree name required")
-    worktree = find_managed(ctx, name)
+    if name:
+        worktree = find_managed(ctx, name)
+    else:
+        # No name, but standing in a managed worktree: that's the one.
+        current = next((w for w in managed_worktrees(ctx) if w.path == ctx.cwd_root), None)
+        if current is None:
+            raise UsageError("worktree name required (or run inside a managed worktree)")
+        worktree = current
     return launch.launch(
         ctx.config,
         main=ctx.main,
@@ -147,28 +196,25 @@ def cmd_open(
 
 def cmd_list(ctx: Context, *, porcelain: bool = False) -> CommandResult:
     worktrees = managed_worktrees(ctx)
-    if porcelain:
-        lines = [
-            "\t".join(
-                (
-                    w.name,
-                    w.branch or "",
-                    str(w.path),
-                    "1" if gitutil.status_porcelain(w.path) else "0",
-                )
-            )
-            for w in worktrees
-        ]
-        return "\n".join(lines)
     if not worktrees:
+        if porcelain:
+            return ""
         output.info(f"no worktrees in {ctx.worktrees_dir} (create one with: wf create BRANCH)")
         return None
+    # One `git status` per worktree; subprocess-bound, so run them together.
+    with ThreadPoolExecutor(max_workers=min(8, len(worktrees))) as pool:
+        dirty = list(pool.map(lambda w: bool(gitutil.status_porcelain(w.path)), worktrees))
+    if porcelain:
+        return "\n".join(
+            "\t".join((w.name, w.branch or "", str(w.path), "1" if is_dirty else "0"))
+            for w, is_dirty in zip(worktrees, dirty, strict=True)
+        )
     name_width = max(len(w.name) for w in worktrees)
     branch_width = max(len(w.branch or "(detached)") for w in worktrees)
     rows = [
         f"{w.name:<{name_width}}  {w.branch or '(detached)':<{branch_width}}  "
-        f"{'dirty' if gitutil.status_porcelain(w.path) else 'clean'}  {w.path}"
-        for w in worktrees
+        f"{'dirty' if is_dirty else 'clean'}  {w.path}"
+        for w, is_dirty in zip(worktrees, dirty, strict=True)
     ]
     return "\n".join(rows)
 
@@ -198,12 +244,14 @@ def cmd_delete(
     delete_branch: bool | None = None,
 ) -> CommandResult:
     result: CommandResult = None
-    for name in names:
-        worktree = find_managed(ctx, name)
+    # Resolve every name first: a typo must fail the batch before anything
+    # is deleted, not strand it half-done.
+    worktrees = [find_managed(ctx, name) for name in names]
+    for worktree in worktrees:
         _confirm_dirty(worktree, "Delete anyway?", force=force)
         branch = worktree.branch
         gitutil.worktree_remove(ctx.main, worktree.path, force=True)
-        output.success(f"deleted worktree {name!r}")
+        output.success(f"deleted worktree {worktree.name!r}")
         if worktree.path == ctx.cwd_root:
             # The shell is standing in the directory we just removed —
             # move it back to the main checkout.
@@ -276,13 +324,13 @@ def cmd_config_show(*, as_json: bool = False) -> CommandResult:
         config = ctx.config
     except NotARepoError:
         config = load_config(None)
-    sources = [(layer, str(path)) for layer, path in config.sources]
     if as_json:
+        sources = [{"layer": s.layer, "path": str(s.path)} for s in config.sources]
         return json.dumps({"config": config.as_dict(), "sources": sources}, indent=2)
     dump = yaml.safe_dump(config.as_dict(), sort_keys=False).rstrip("\n")
     lines = [dump, "", "# sources (low -> high):"]
-    if sources:
-        lines.extend(f"#   {layer}: {path}" for layer, path in sources)
+    if config.sources:
+        lines.extend(f"#   {s.layer}: {s.path}" for s in config.sources)
     else:
         lines.append("#   (built-in defaults only)")
     return "\n".join(lines)