devlaunch 0.0.19__tar.gz → 0.0.21__tar.gz

{devlaunch-0.0.19 → devlaunch-0.0.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devlaunch
-Version: 0.0.19
+Version: 0.0.21
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -339,6 +339,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 | Command | Description |
 |---------|-------------|
 | `dl --ls` | List all workspaces |
+| `dl --ls --json` | The same list as JSON, with each workspace's repo, branch, state and [unsaved work](#cleaning-up-workspaces) — for tools that decide what to clean up |
 | `dl --install` | Install shell completions |
 | `dl --purge [-y]` | Remove all devlaunch data — [the workspaces devlaunch created](#what-purge-deletes), and its caches |
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
@@ -396,6 +397,63 @@ Erring this way is deliberate — a purge that skips one of your own workspaces
 costs you a command, and the other kind of mistake costs you work you cannot get
 back.
 
+### Cleaning up workspaces
+
+One workspace per branch means workspaces accumulate, and `--purge` is the wrong
+tool for tidying: it is all-or-nothing and takes the caches with it.
+
+**devlaunch does not decide which workspaces are finished.** Whether a piece of
+work is over is a fact about a ticket, a review, or somebody's intent, and `dl`
+knows about clones and containers. Inferring it from the branch — merged into
+the default, or deleted from the remote — was tried and dropped: it reads like a
+git fact but is a guess at intent, and it cannot tell a squash-merged branch
+from an abandoned one. So `dl` supplies the two halves a tool that *does* know
+needs, and that tool drives the cleanup:
+
+```bash
+dl --ls --json     # what exists, and what each workspace holds
+dl <workspace> rm  # remove one
+```
+
+The JSON reports, per workspace: `id`, `devlaunch` (did `dl` create it),
+`repo`, `branch` (what the workspace was made for), `checkedOut` (what its clone
+is on now, which can differ), `path`, `state`, `lastUsed`, and — the field a
+cleanup tool must not ignore — `unsaved`:
+
+```json
+{
+  "id": "devlaunch-wayfinder-devlaunch-80-ladepomi",
+  "devlaunch": true,
+  "repo": "blooop/devlaunch",
+  "branch": "wayfinder/devlaunch-80",
+  "state": "Stopped",
+  "unsaved": "2 uncommitted change(s) and 1 unpushed commit(s)"
+}
+```
+
+`unsaved` is a description of what deleting would destroy, or `null` when the
+clone holds nothing that does not also exist on a remote — uncommitted changes
+(untracked files included) and commits no remote has. A workspace `dl` did not
+create reports `devlaunch: false` with no repo, branch or `unsaved`: there is no
+clone of `dl`'s to protect, and it has no business inspecting your checkout.
+
+**`dl <workspace> rm` refuses when the clone holds unsaved work**, so a caller
+that forgets to read the field is still caught:
+
+```
+$ dl blooop/repo@feature rm
+error: devlaunch-repo-feature-xyz holds 1 unpushed commit(s).
+       Push or commit it, or run: dl blooop/repo@feature rm --force
+```
+
+That refusal is the only judgement `dl` makes here, and it is not about finished
+work — it is `dl` declining to destroy the only copy of something. Say `--force`
+if you mean it.
+
+[`wf`](https://github.com/blooop/wayfinder) is the caller this was built for: it
+names its branches after its tickets, so it knows which workspaces belong to
+finished work and removes those.
+
 ## Examples
 
 ```bash

{devlaunch-0.0.19 → devlaunch-0.0.21}/README.md

@@ -317,6 +317,7 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 | Command | Description |
 |---------|-------------|
 | `dl --ls` | List all workspaces |
+| `dl --ls --json` | The same list as JSON, with each workspace's repo, branch, state and [unsaved work](#cleaning-up-workspaces) — for tools that decide what to clean up |
 | `dl --install` | Install shell completions |
 | `dl --purge [-y]` | Remove all devlaunch data — [the workspaces devlaunch created](#what-purge-deletes), and its caches |
 | `dl --prune-worktrees [days]` | Remove unused worktrees (default: 30 days) |
@@ -374,6 +375,63 @@ Erring this way is deliberate — a purge that skips one of your own workspaces
 costs you a command, and the other kind of mistake costs you work you cannot get
 back.
 
+### Cleaning up workspaces
+
+One workspace per branch means workspaces accumulate, and `--purge` is the wrong
+tool for tidying: it is all-or-nothing and takes the caches with it.
+
+**devlaunch does not decide which workspaces are finished.** Whether a piece of
+work is over is a fact about a ticket, a review, or somebody's intent, and `dl`
+knows about clones and containers. Inferring it from the branch — merged into
+the default, or deleted from the remote — was tried and dropped: it reads like a
+git fact but is a guess at intent, and it cannot tell a squash-merged branch
+from an abandoned one. So `dl` supplies the two halves a tool that *does* know
+needs, and that tool drives the cleanup:
+
+```bash
+dl --ls --json     # what exists, and what each workspace holds
+dl <workspace> rm  # remove one
+```
+
+The JSON reports, per workspace: `id`, `devlaunch` (did `dl` create it),
+`repo`, `branch` (what the workspace was made for), `checkedOut` (what its clone
+is on now, which can differ), `path`, `state`, `lastUsed`, and — the field a
+cleanup tool must not ignore — `unsaved`:
+
+```json
+{
+  "id": "devlaunch-wayfinder-devlaunch-80-ladepomi",
+  "devlaunch": true,
+  "repo": "blooop/devlaunch",
+  "branch": "wayfinder/devlaunch-80",
+  "state": "Stopped",
+  "unsaved": "2 uncommitted change(s) and 1 unpushed commit(s)"
+}
+```
+
+`unsaved` is a description of what deleting would destroy, or `null` when the
+clone holds nothing that does not also exist on a remote — uncommitted changes
+(untracked files included) and commits no remote has. A workspace `dl` did not
+create reports `devlaunch: false` with no repo, branch or `unsaved`: there is no
+clone of `dl`'s to protect, and it has no business inspecting your checkout.
+
+**`dl <workspace> rm` refuses when the clone holds unsaved work**, so a caller
+that forgets to read the field is still caught:
+
+```
+$ dl blooop/repo@feature rm
+error: devlaunch-repo-feature-xyz holds 1 unpushed commit(s).
+       Push or commit it, or run: dl blooop/repo@feature rm --force
+```
+
+That refusal is the only judgement `dl` makes here, and it is not about finished
+work — it is `dl` declining to destroy the only copy of something. Say `--force`
+if you mean it.
+
+[`wf`](https://github.com/blooop/wayfinder) is the caller this was built for: it
+names its branches after its tickets, so it knows which workspaces belong to
+finished work and removes those.
+
 ## Examples
 
 ```bash

{devlaunch-0.0.19 → devlaunch-0.0.21}/devlaunch/dl.py

@@ -27,12 +27,13 @@ import re
 import shlex
 import time
 from importlib.metadata import version as pkg_version, PackageNotFoundError, distribution
+from pathlib import Path
 from typing import Any, Dict, List, Mapping, NoReturn, Optional, Sequence, Tuple
 from dataclasses import dataclass
 from urllib.parse import urlparse
 from urllib.request import url2pathname
 
-from . import devpod_ssh, gh_auth, tools, tty_session
+from . import devpod_ssh, gh_auth, tools, tty_session, workspace_state
 from .completion import install_completions
 from .workspace_id import TARGET_LENGTH, WorkspaceId, slug, source_workspace_id, validate_ref_name
 from .worktree.config import get_worktree_config
@@ -431,6 +432,76 @@ def update_cache_background(force: bool = False) -> None:
         pass
 
 
+def _unsaved_work_in(workspace_id: str) -> Optional[str]:
+    """What deleting *workspace_id* would destroy, or None if nothing would be.
+
+    Answers None for a workspace devlaunch has no record of, which is the honest
+    answer rather than a permissive one: those are workspaces opened from a path
+    or a URL that dl never cloned and does not manage, so it has no clone of its
+    own to protect and no business inspecting someone's checkout to find one.
+    """
+    try:
+        record = _get_clone_manager().storage.get_worktree_by_workspace_id(workspace_id)
+    except (OSError, RuntimeError) as e:
+        logging.debug(f"could not read the workspace record for {workspace_id}: {e}")
+        return None
+    if record is None:
+        return None
+    return workspace_state.holds_unsaved_work(Path(record.local_path))
+
+
+def workspaces_as_json() -> int:
+    """Print the workspace list as JSON: what exists, and what each one holds.
+
+    The machine-readable half of cleanup. devlaunch does not decide which
+    workspaces are finished -- that is a fact about tickets, reviews and intent,
+    none of which it knows -- so it reports what it does know and lets the
+    caller that knows the rest decide. `wf` is one such caller: it named the
+    branches after its tickets, so matching a workspace to a ticket is its
+    business, not dl's.
+
+    Every field is something dl can answer for certain:
+
+    - `repo` and `branch` come from the record dl wrote when it made the clone;
+      a workspace dl did not make has neither, and says so with `devlaunch:
+      false` rather than a guess.
+    - `unsaved` is the field a caller must not ignore: a description of what
+      deleting would destroy, or null. `dl <ws> rm` refuses on it too, so a
+      caller that forgets is still caught -- but a caller that reads it can
+      leave the workspace alone instead of arguing with a refusal.
+    - `state` is devpod's, one `devpod status` per workspace, which is why this
+      is a command someone runs rather than something on the fast path.
+    """
+    cache_dir = _get_cache_dir()
+    workspaces = list_workspaces()
+    clone_mgr = _get_clone_manager()
+    report: List[Dict[str, Any]] = []
+    for ws in workspaces:
+        mine = is_devlaunch_clone(ws, cache_dir)
+        record = clone_mgr.storage.get_worktree_by_workspace_id(ws.id) if mine else None
+        clone_path = Path(record.local_path) if record else None
+        state = workspace_state.read_clone(clone_path) if clone_path else None
+        report.append(
+            {
+                "id": ws.id,
+                "devlaunch": mine,
+                "repo": f"{record.owner}/{record.repo}" if record else None,
+                # The recorded branch is what the workspace was made for; the
+                # clone's current HEAD can differ (an agent checked something
+                # else out), so both are reported rather than one being made to
+                # stand for the other.
+                "branch": record.branch if record else None,
+                "checkedOut": state.branch if state else None,
+                "path": str(clone_path) if clone_path else None,
+                "state": get_workspace_state(ws.id),
+                "lastUsed": ws.last_used,
+                "unsaved": state.unsaved if state else None,
+            }
+        )
+    print(json.dumps(report, indent=2))
+    return 0
+
+
 def purge_all_data() -> int:
     """Purge devlaunch's data: the workspaces it created, and its caches.
 
@@ -1609,7 +1680,9 @@ Workspace sources:
 
 Workspace commands:
     dl <user/repo> stop              Stop the workspace
-    dl <user/repo> rm, prune         Delete the workspace
+    dl <user/repo> rm, prune         Delete the workspace. Refuses if its clone
+                                     holds uncommitted or unpushed work; add
+                                     --force to delete it anyway.
     dl <user/repo> code              Open in VS Code
     dl <user/repo> restart           Stop and start (no rebuild)
     dl <user/repo> recreate          Recreate container
@@ -1618,6 +1691,10 @@ Workspace commands:
 
 Global commands:
     dl --ls                          List all workspaces
+    dl --ls --json                   List them as JSON, with each one's repo,
+                                     branch, state, and what it holds that is
+                                     not pushed anywhere ("unsaved"). For tools
+                                     that decide which workspaces to clean up.
     dl --install                     Install shell completions
     dl --refresh                     Refresh completion cache
     dl --purge [-y]                  Remove devlaunch's workspaces and caches
@@ -1659,7 +1736,12 @@ def _get_clone_manager() -> WorkspaceCloneManager:
     if "clone_manager" not in _cache:
         manager = WorkspaceCloneManager()
         try:
-            migrate_cache(manager.storage, pathlib.Path(manager.config.repos_dir))
+            # Under the metadata lock so two dl processes cannot migrate at
+            # once: the renames are not idempotent mid-flight, and exclusive()
+            # reloads first so the version check sees the other side's result.
+            # migrate_cache calls save() directly, never a locked mutator.
+            with manager.storage.exclusive():
+                migrate_cache(manager.storage, pathlib.Path(manager.config.repos_dir))
         except OSError as e:
             # A failed migration must not take the command with it. The renames
             # that did happen are still resumable: the version header is only
@@ -1755,6 +1837,8 @@ def _run_cli(argv: Optional[List[str]] = None) -> int:
         return 0
 
     if args[0] == "--ls":
+        if "--json" in args[1:]:
+            return workspaces_as_json()
         print_workspaces()
         return 0
 
@@ -1941,6 +2025,20 @@ def _run_cli(argv: Optional[List[str]] = None) -> int:
         return workspace_stop(workspace_id)
 
     if subcommand in ("rm", "prune"):
+        # The one thing dl refuses on its own account. It is not a judgement
+        # about whether the work is finished -- dl has no way to know that --
+        # but about whether this clone is the only place the work exists.
+        # Cleanup is expected to be driven by something that knows more than dl
+        # does (a ticket tool, a script, a person), and this is what keeps a
+        # confident caller from destroying an hour of somebody's afternoon.
+        if "--force" not in args[2:]:
+            unsaved = _unsaved_work_in(workspace_id)
+            if unsaved:
+                logging.error(
+                    f"{workspace_id} holds {unsaved}. Push or commit it, or run: "
+                    f"dl {raw_spec} rm --force"
+                )
+                return 1
         return workspace_delete(workspace_id)
 
     if subcommand == "code":

devlaunch-0.0.21/devlaunch/workspace_state.py

@@ -0,0 +1,121 @@
+"""What a workspace holds — the facts a cleanup decision is made from elsewhere.
+
+A workspace per branch means workspaces accumulate, and something has to remove
+the finished ones. That something is **not devlaunch**: whether a piece of work
+is finished is a fact about a ticket, a review or a person's intent, and dl
+knows about none of those. It knows about clones and containers.
+
+So the split is mechanism here, policy in the caller:
+
+- ``dl --ls --json`` reports what exists and what each workspace holds, which is
+  what a caller needs to decide anything at all.
+- ``dl <ws> rm`` deletes one, and refuses when the clone holds work that exists
+  nowhere else.
+
+The refusal is the one judgement dl does make, and it is not a policy about
+finished work: it is dl declining to destroy the only copy of something. A
+caller that means it says ``--force``.
+
+The alternative — dl inferring "finished" from the branch (merged into the
+default, or deleted from the remote) — was built first and thrown away. It reads
+as a git fact but it is a guess at intent: a squash-merged branch and an
+abandoned one are indistinguishable, a branch merged upstream may still have
+work to do, and a repo whose flow does not delete branches gets nothing. The
+caller that knows the answer should say the answer.
+"""
+
+import logging
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class CloneState:
+    """What one workspace clone holds, as far as git can tell.
+
+    ``unsaved`` is the load-bearing field and is deliberately a description
+    rather than a flag: it is printed to a person who is deciding whether to
+    force a delete, and "3 uncommitted change(s) and 2 unpushed commit(s)" is
+    the thing that answers them. ``None`` means the clone holds nothing that
+    does not also exist on a remote.
+    """
+
+    branch: Optional[str]
+    unsaved: Optional[str]
+
+
+def _git(repo: Path, *args: str) -> Optional[str]:
+    """Run git in *repo*, returning stdout, or ``None`` if it refused.
+
+    A refusal is "cannot tell", never an answer: a clone that is broken, gone or
+    not a repository must not stop the other workspaces being reported, and must
+    never be reported as *safe to delete* on the strength of a failed command —
+    every caller here treats ``None`` as "no information", and the one place
+    that matters (:func:`holds_unsaved_work`) fails safe explicitly.
+    """
+    try:
+        result = subprocess.run(
+            ["git", *args], cwd=repo, capture_output=True, text=True, check=False, timeout=30
+        )
+    except (OSError, subprocess.SubprocessError) as e:
+        logger.debug(f"git {' '.join(args)} in {repo}: {e}")
+        return None
+    if result.returncode != 0:
+        logger.debug(f"git {' '.join(args)} in {repo}: {result.stderr.strip()}")
+        return None
+    return result.stdout.strip()
+
+
+def read_clone(clone: Path) -> CloneState:
+    """Report what *clone* holds. The only function here that talks to git.
+
+    A directory that is not there, or is not a repository, holds nothing: there
+    is no work in it to lose. That is the truth about it rather than a special
+    case, and it is what lets a caller clear away a workspace whose clone was
+    already removed by hand.
+    """
+    if not clone.is_dir():
+        return CloneState(branch=None, unsaved=None)
+    branch = _git(clone, "rev-parse", "--abbrev-ref", "HEAD")
+    return CloneState(branch=branch or None, unsaved=_unsaved(clone, branch))
+
+
+def _unsaved(clone: Path, branch: Optional[str]) -> Optional[str]:
+    """What deleting *clone* would destroy, in words, or ``None`` if nothing.
+
+    Two kinds of loss, reported together because someone deciding whether to
+    force a delete wants both:
+
+    - a dirty tree, **untracked files included** — an agent's scratch notes are
+      not less lost for never having been added;
+    - commits no remote-tracking ref contains. ``--not --remotes`` asks about
+      *any* remote ref rather than this branch's upstream, so work that was
+      pushed under another name, or merged and fetched back, is correctly not
+      counted as lost.
+    """
+    losses: List[str] = []
+    status = _git(clone, "status", "--porcelain")
+    if status:
+        losses.append(f"{len(status.splitlines())} uncommitted change(s)")
+    if branch:
+        # Argument order is load-bearing: `--not` flips the sense of every ref
+        # *after* it, so the branch has to be named before it. `log --not
+        # --remotes <branch>` excludes the branch as well and is silently always
+        # empty — which would report every clone as safe to delete.
+        unpushed = _git(clone, "log", "--oneline", branch, "--not", "--remotes")
+        if unpushed:
+            losses.append(f"{len(unpushed.splitlines())} unpushed commit(s)")
+    return " and ".join(losses) if losses else None
+
+
+def holds_unsaved_work(clone: Path) -> Optional[str]:
+    """What would be lost by deleting *clone*, or ``None`` if nothing would be.
+
+    The guard `dl <ws> rm` consults. Thin on purpose: the interesting behaviour
+    is in :func:`read_clone`, and this is the name the guard reads by.
+    """
+    return read_clone(clone).unsaved

devlaunch-0.0.21/devlaunch/worktree/locks.py

@@ -0,0 +1,55 @@
+"""Inter-process locks for the shared cache.
+
+Several dl processes can run at once — two agents launched on their own
+branches, a completion refresh in the background — and they share one bare-clone
+cache and one metadata.json. These locks are what keeps simultaneous runs from
+racing each other over that state: without them, two first launches of a repo
+both ran ``git clone --bare`` into the same path (and the loser's cleanup
+deleted the winner's half-written clone), and metadata writers rewrote the file
+from stale in-memory copies, dropping each other's records.
+
+``flock`` rather than a pid file: the kernel releases it when the process dies,
+however it dies, so a crashed dl never leaves the cache wedged.
+
+Two deliberate limits, both load-bearing:
+
+- **Not reentrant.** Acquiring a path twice in one process deadlocks (the second
+  open file description blocks on the first). Call sites are structured so no
+  lock is ever taken while the same lock is held — see the acquisition comments
+  at each site.
+- **The lock file is never deleted.** Unlinking an flock'd file is the classic
+  self-defeating move: a process that opened the old inode still "holds" a lock
+  nobody else can see, while new arrivals lock a fresh file and walk straight
+  past it. A few empty ``.lock`` files in the cache are the price of the
+  guarantee; ``dl --purge`` sweeps them away with everything else.
+"""
+
+import contextlib
+import fcntl
+import os
+import sys
+from pathlib import Path
+from typing import Iterator, Optional
+
+
+@contextlib.contextmanager
+def hold_lock(lock_path: Path, waiting_note: Optional[str] = None) -> Iterator[None]:
+    """Hold an exclusive inter-process lock on *lock_path* for the block.
+
+    Blocks until the lock is free. When another process already holds it and
+    *waiting_note* is given, one line is printed to stderr first, so a dl run
+    that sits waiting on a sibling's long clone says why it is sitting.
+    """
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            if waiting_note:
+                print(f"dl: waiting for {waiting_note}", file=sys.stderr)
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        # Closing the descriptor releases the lock; nothing is unlinked.
+        os.close(fd)

{devlaunch-0.0.19 → devlaunch-0.0.21}/devlaunch/worktree/repo_manager.py

@@ -7,6 +7,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import Optional, TYPE_CHECKING
 
+from .locks import hold_lock
 from .models import BaseRepository
 from .storage import MetadataStorage
 
@@ -41,6 +42,15 @@ class RepositoryManager:
         """Get the bare git directory for a repository."""
         return self.get_repo_path(owner, repo) / ".bare"
 
+    def lock_path(self, owner: str, repo: str) -> Path:
+        """The lock every process takes before mutating repos/<owner>/<repo>.
+
+        A file, not a directory, inside the repo dir: every walker of the cache
+        filters on ``is_dir()``, so it is invisible to discovery, migration and
+        completion scans.
+        """
+        return self.get_repo_path(owner, repo) / ".lock"
+
     def clone_repo(self, owner: str, repo: str, remote_url: str) -> BaseRepository:
         """Clone a new base repository as bare (no working directory).
 
@@ -58,7 +68,21 @@ class RepositoryManager:
             existing_repo = self.get_repo(owner, repo)
             if existing_repo:
                 return existing_repo
-            # Repository path exists but metadata doesn't - continue to create metadata
+            if (bare_path / "HEAD").exists():
+                # The bare clone is already on disk but this process has no
+                # record of it -- another process just made it (this process's
+                # metadata was loaded before that one saved), or an earlier run
+                # died between clone and save. Either way the clone on disk is
+                # the authority and the record is derived state: rebuild the
+                # record. Cloning over it instead is not an option -- git
+                # refuses the non-empty destination, and the failure cleanup
+                # below would then delete a cache another launch is using.
+                return self._register_existing_bare(owner, repo, remote_url, bare_path)
+            # No HEAD: a dead run's partial clone. Holding the repo lock (every
+            # caller comes through ensure_repo) means no live process owns it,
+            # so clear it and clone fresh.
+            logger.warning(f"Removing partial clone at {bare_path}")
+            shutil.rmtree(bare_path)
 
         # Create parent directory
         bare_path.parent.mkdir(parents=True, exist_ok=True)
@@ -97,11 +121,28 @@ class RepositoryManager:
 
         except subprocess.CalledProcessError as e:
             logger.debug(f"Failed to clone repository: {e.stderr}")
-            # Clean up partial clone
+            # Clean up the partial clone. Safe to delete: the exists-cases were
+            # all handled above, so this directory is one this call created.
             if bare_path.exists():
                 shutil.rmtree(bare_path)
             raise RuntimeError(f"Failed to clone repository: {e.stderr}") from e
 
+    def _register_existing_bare(
+        self, owner: str, repo: str, remote_url: str, bare_path: Path
+    ) -> BaseRepository:
+        """Rebuild the metadata record for a bare clone already on disk."""
+        base_repo = BaseRepository(
+            owner=owner,
+            repo=repo,
+            remote_url=remote_url,
+            local_path=bare_path,
+            default_branch=self._get_default_branch(bare_path),
+            last_fetched=datetime.now(),
+            worktrees=[],
+        )
+        self.storage.add_repository(base_repo)
+        return base_repo
+
     def fetch_repo(self, owner: str, repo: str) -> None:
         """Fetch latest changes from remote."""
         bare_path = self.get_bare_path(owner, repo)
@@ -166,20 +207,33 @@ class RepositoryManager:
         """Ensure repo exists locally, clone if needed.
 
         Uses lazy fetch: only fetches if fetch_interval has elapsed since last fetch.
-        """
-        if self.repo_exists(owner, repo):
-            existing_repo = self.get_repo(owner, repo)
-            if existing_repo:
-                # Only fetch if interval has elapsed (lazy fetch)
-                if auto_fetch and self._should_fetch(existing_repo):
-                    try:
-                        self.fetch_repo(owner, repo)
-                    except Exception as e:
-                        logger.warning(f"Failed to fetch updates: {e}")
-                return existing_repo
-            # Metadata doesn't exist but repo exists - fall through to clone (which will add metadata)
 
-        return self.clone_repo(owner, repo, remote_url)
+        The whole exists-check-then-clone sequence runs under the repo lock:
+        without it, two processes launching the same repo at once both saw no
+        clone and both ran ``git clone --bare`` into the same path — and the
+        loser's cleanup in clone_repo deleted the winner's half-written cache.
+        Serialized, the loser just waits and then reuses the winner's clone.
+        clone_repo and fetch_repo rely on this lock rather than taking it
+        themselves (hold_lock is not reentrant).
+        """
+        with hold_lock(
+            self.lock_path(owner, repo),
+            waiting_note=f"another dl run preparing {owner}/{repo}",
+        ):
+            if self.repo_exists(owner, repo):
+                existing_repo = self.get_repo(owner, repo)
+                if existing_repo:
+                    # Only fetch if interval has elapsed (lazy fetch)
+                    if auto_fetch and self._should_fetch(existing_repo):
+                        try:
+                            self.fetch_repo(owner, repo)
+                        except Exception as e:
+                            logger.warning(f"Failed to fetch updates: {e}")
+                    return existing_repo
+                # Metadata doesn't exist but repo exists - fall through to clone
+                # (which will add metadata)
+
+            return self.clone_repo(owner, repo, remote_url)
 
     def repo_exists(self, owner: str, repo: str) -> bool:
         """Check if repository exists locally."""

{devlaunch-0.0.19 → devlaunch-0.0.21}/devlaunch/worktree/storage.py

@@ -12,6 +12,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 from devlaunch.xdg import devlaunch_cache
 
+from .locks import hold_lock
 from .models import BaseRepository, WorktreeInfo, unknown_fields
 
 # Version of the on-disk metadata.json format.
@@ -83,8 +84,28 @@ class MetadataStorage:
         self.metadata_path.parent.mkdir(parents=True, exist_ok=True)
         # Every file operation targets the real file, not a symlink pointing at it.
         self._file_path = _resolve_link(self.metadata_path)
+        # A sidecar rather than the file itself: save() replaces metadata.json
+        # by rename, and a lock taken on a replaced inode guards nothing.
+        self._lock_path = self._file_path.with_name(self._file_path.name + ".lock")
         self._load()
 
+    @contextlib.contextmanager
+    def exclusive(self):
+        """Hold the metadata lock and reload before the block runs.
+
+        Every mutation goes through this: the in-memory copy was loaded whenever
+        this process started, and other dl processes may have written since.
+        Rewriting the file from that stale copy silently drops their records —
+        reloading under the lock is what makes read-modify-write safe. The
+        caller applies its change and calls save() before the block ends.
+
+        Not reentrant (see locks.py), so mutators must never be called from
+        inside an exclusive() block — they take this lock themselves.
+        """
+        with hold_lock(self._lock_path, waiting_note="another dl run updating the workspace list"):
+            self._load()
+            yield
+
     def _quarantine(self, reason: str) -> None:
         """Move an unusable metadata file aside so the data stays inspectable.
 
@@ -288,8 +309,9 @@ class MetadataStorage:
     def add_repository(self, repo: BaseRepository) -> None:
         """Add or update a repository."""
         key = f"{repo.owner}/{repo.repo}"
-        self.repositories[key] = repo
-        self.save()
+        with self.exclusive():
+            self.repositories[key] = repo
+            self.save()
 
     def get_repository(self, owner: str, repo: str) -> Optional[BaseRepository]:
         """Get a repository by owner and name."""
@@ -303,22 +325,24 @@ class MetadataStorage:
     def remove_repository(self, owner: str, repo: str) -> None:
         """Remove a repository."""
         key = f"{owner}/{repo}"
-        if key in self.repositories:
-            del self.repositories[key]
-            self.save()
+        with self.exclusive():
+            if key in self.repositories:
+                del self.repositories[key]
+                self.save()
 
     def add_worktree(self, worktree: WorktreeInfo) -> None:
         """Add or update a worktree."""
         key = f"{worktree.owner}/{worktree.repo}/{worktree.branch}"
-        self.worktrees[key] = worktree
+        with self.exclusive():
+            self.worktrees[key] = worktree
 
-        # Update repository's worktree list in memory, then write once.
-        repo = self.get_repository(worktree.owner, worktree.repo)
-        if repo and worktree.branch not in repo.worktrees:
-            repo.worktrees.append(worktree.branch)
-            self.repositories[f"{worktree.owner}/{worktree.repo}"] = repo
+            # Update repository's worktree list in memory, then write once.
+            repo = self.get_repository(worktree.owner, worktree.repo)
+            if repo and worktree.branch not in repo.worktrees:
+                repo.worktrees.append(worktree.branch)
+                self.repositories[f"{worktree.owner}/{worktree.repo}"] = repo
 
-        self.save()
+            self.save()
 
     def get_worktree(self, owner: str, repo: str, branch: str) -> Optional[WorktreeInfo]:
         """Get a worktree by repository and branch."""
@@ -348,13 +372,14 @@ class MetadataStorage:
     def remove_worktree(self, owner: str, repo: str, branch: str) -> None:
         """Remove a worktree."""
         key = f"{owner}/{repo}/{branch}"
-        if key in self.worktrees:
-            del self.worktrees[key]
+        with self.exclusive():
+            if key in self.worktrees:
+                del self.worktrees[key]
 
-            # Update repository's worktree list in memory, then write once.
-            repo_obj = self.get_repository(owner, repo)
-            if repo_obj and branch in repo_obj.worktrees:
-                repo_obj.worktrees.remove(branch)
-                self.repositories[f"{owner}/{repo}"] = repo_obj
+                # Update repository's worktree list in memory, then write once.
+                repo_obj = self.get_repository(owner, repo)
+                if repo_obj and branch in repo_obj.worktrees:
+                    repo_obj.worktrees.remove(branch)
+                    self.repositories[f"{owner}/{repo}"] = repo_obj
 
-            self.save()
+                self.save()

{devlaunch-0.0.19 → devlaunch-0.0.21}/devlaunch/worktree/workspace_clone.py

@@ -25,6 +25,7 @@ from typing import Optional
 from ..workspace_id import WorkspaceId, validate_ref_name
 from .branch_manager import BranchManager
 from .config import WorktreeConfig, get_worktree_config
+from .locks import hold_lock
 from .models import WorktreeInfo
 from .repo_manager import RepositoryManager
 from .storage import MetadataStorage
@@ -173,27 +174,36 @@ class WorkspaceCloneManager:
 
         Fetches latest refs, then uses BranchManager to create the branch
         locally if needed. Does not push to the remote.
+
+        Runs under the repo lock: the fetch and the branch creation both write
+        refs in the shared bare repo, and two processes doing so at once trip
+        over git's own ref locks. (hold_lock is not reentrant; no callee here
+        takes the repo lock.)
         """
         bare_path = self.repo_manager.get_bare_path(owner, repo)
-        # Lazy-fetch: only hits the network when the fetch interval has elapsed
-        try:
-            self.repo_manager.lazy_fetch(owner, repo)
-        except (RuntimeError, ValueError, OSError) as e:
-            logger.warning(f"Failed to fetch before branch ensure: {e}")
+        with hold_lock(
+            self.repo_manager.lock_path(owner, repo),
+            waiting_note=f"another dl run preparing {owner}/{repo}",
+        ):
+            # Lazy-fetch: only hits the network when the fetch interval has elapsed
+            try:
+                self.repo_manager.lazy_fetch(owner, repo)
+            except (RuntimeError, ValueError, OSError) as e:
+                logger.warning(f"Failed to fetch before branch ensure: {e}")
 
-        try:
-            default_branch = self.repo_manager.get_default_branch(owner, repo)
-        except (RuntimeError, subprocess.CalledProcessError, OSError) as e:
-            logger.warning(f"Failed to resolve default branch: {e}")
-            default_branch = None
-
-        self.branch_manager.ensure_branch_exists(
-            bare_path,
-            branch,
-            create_remote=False,
-            start_point=default_branch or "HEAD",
-            use_local_refs=True,
-        )
+            try:
+                default_branch = self.repo_manager.get_default_branch(owner, repo)
+            except (RuntimeError, subprocess.CalledProcessError, OSError) as e:
+                logger.warning(f"Failed to resolve default branch: {e}")
+                default_branch = None
+
+            self.branch_manager.ensure_branch_exists(
+                bare_path,
+                branch,
+                create_remote=False,
+                start_point=default_branch or "HEAD",
+                use_local_refs=True,
+            )
 
     def ensure_workspace(
         self,
@@ -223,6 +233,28 @@ class WorkspaceCloneManager:
         bare_repo_path = self.repo_manager.get_bare_path(owner, repo)
 
         ws_path = self.get_workspace_path(owner, repo, branch)
+
+        # Steps 2-6 mutate the workspace clone, so they run under the repo
+        # lock: fire the same workspace twice at once and, unserialized, each
+        # process saw no clone, both cloned into the same path, and the loser's
+        # cleanup deleted the winner's. The lock is taken only after
+        # ensure_repo (which takes the same lock) has returned -- hold_lock is
+        # not reentrant.
+        with hold_lock(
+            self.repo_manager.lock_path(owner, repo),
+            waiting_note=f"another dl run preparing {owner}/{repo}",
+        ):
+            return self._prepare_workspace(workspace, bare_repo_path, ws_path, remote_url)
+
+    def _prepare_workspace(
+        self,
+        workspace: WorkspaceId,
+        bare_repo_path: Path,
+        ws_path: Path,
+        remote_url: str,
+    ) -> Path:
+        """Steps 2-6 of ensure_workspace; the caller holds the repo lock."""
+        owner, repo, branch = workspace.owner, workspace.repo, workspace.ref
         is_new_workspace = False
         if not self.workspace_exists(owner, repo, branch):
             is_new_workspace = True

{devlaunch-0.0.19 → devlaunch-0.0.21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devlaunch"
-version = "0.0.19"
+version = "0.0.21"
 authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }]
 description = "DevLaunch - A streamlined CLI for devpod workspaces"
 readme = "README.md"