devlaunch 0.0.24__tar.gz → 0.0.26__tar.gz

{devlaunch-0.0.24 → devlaunch-0.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: devlaunch
-Version: 0.0.24
+Version: 0.0.26
 Summary: DevLaunch - A streamlined CLI for devpod workspaces
 Project-URL: Source, https://github.com/blooop/devlaunch
 Project-URL: Home, https://github.com/blooop/devlaunch
@@ -242,6 +242,7 @@ than the filesystem has actually done.
 | `dl <user/repo> restart` | Stop and start (no rebuild) |
 | `dl <user/repo> recreate` | Recreate container |
 | `dl <user/repo> reset` | Clean slate (remove all, recreate) |
+| `dl <user/repo> dotfiles` | Refresh dotfiles in the running workspace (`chezmoi update`) |
 | `dl <user/repo> -- <command>` | Run shell command in workspace (with a terminal, when `dl` has one) |
 
 ## Options
@@ -313,16 +314,96 @@ and `aid`. The repo's `devcontainer.json` does not have to provide them, and mos
 do not: `dl` launches arbitrary repos, so a guarantee that depended on the image
 would not be a guarantee.
 
-They are installed with `pixi global` on `devpod up`, and put on the PATH of a
-login shell through whichever of `~/.bash_profile`, `~/.bash_login` or `~/.profile`
-bash actually reads — it sources only the first of those that exists, so an image
-shipping a `~/.bash_profile` never reads `~/.profile`. A workspace that already has both is left alone —
-the check runs first, so the cost after the first launch is one round-trip and no
-network. If `pixi` is missing from the image, `dl` installs that too.
+### How they get there
+
+On `devpod up`, at most three round trips, each one earning the next.
+
+**1. A probe — the only trip a ready workspace ever pays.** The container reports
+what only it can know: whether both tools answer at all, where its `claude`
+resolves to, and where `~/.local/share/claude/versions` in its own home resolves
+to. It reports those and names no verdict; the host reads them, so "a real
+`claude`" is defined in exactly one place. The reading is one of three:
+
+- **provisioned** — `gh` answers on the login PATH and `claude` resolves to a
+  binary the official installer put in the versions directory. Nothing else
+  happens.
+- **lendable** — both names answer, but that `claude` is a shim or a wrapper.
+- **absent** — a tool is genuinely missing.
+
+**2. A lend, for *lendable* and *absent*.** `dl` streams its own `gh` and `claude`
+into the container as a tar over the `devpod ssh` channel it already holds — a
+local pipe, no network and no download. Nothing lands outside a staging directory
+until both binaries have been run there once, so a container that cannot execute
+them (a different libc, a different architecture) is left exactly as it was.
+
+**3. The network install, for *absent* only.** When the host had nothing to lend,
+or the lend was refused, `pixi global` installs both tools — and `pixi` itself
+first if the image has none. A *lendable* container never reaches this trip: it
+stops after the lend, or — when the host had nothing to lend — after the probe
+itself. A `claude` already answers there, and this install decides what to do
+with the same `command -v` that a shim satisfies, so the trip would install
+nothing.
+
+Tools reach the PATH of a login shell through whichever of `~/.bash_profile`,
+`~/.bash_login` or `~/.profile` bash actually reads — it sources only the first of
+those that exists, so an image shipping a `~/.bash_profile` never reads
+`~/.profile`.
 
 An install that fails costs the workspace its tools, not its launch: `dl` logs a
 warning and hands you the session anyway.
 
+### What to bake so a launch does no work at all
+
+To make every `dl` launch of an image stop at trip 1. The probe asks a **login**
+shell to resolve each name, so every bullet here is about what a login shell can
+find:
+
+- **`gh`** anywhere on the login PATH.
+- **`claude`** in the layout its official installer creates — the binary at
+  `~/.local/share/claude/versions/<version>`, a **direct child** of that
+  directory named for the version, with `~/.local/bin/claude` symlinked to it.
+  Nested any deeper — `versions/<version>/bin/claude`, the shape a downloader
+  parked there would take — is read as somebody else's tree that merely starts
+  with the official path, and does not count.
+- **`~/.local/bin` on the login PATH**. The symlink above is how `claude`
+  answers at all; a login shell that cannot find that directory reads the image
+  as *absent* however carefully the rest was baked, and it pays the full lend.
+  Ubuntu's stock `~/.profile` prepends `~/.local/bin` itself — but an image
+  shipping a `~/.bash_profile` never reads `~/.profile` (above), and then
+  nothing does.
+
+Nothing else counts as a `claude`, and that is the point. A *shim* — a small
+launcher that downloads the real binary the first time it is called — answers
+`command -v claude` exactly as the real thing does, while the workspace still
+owes a multi-hundred-megabyte download at the least convenient moment. So `dl`
+resolves the name rather than running it (running a shim *is* the download), reads
+a shim as *lendable*, and sends the host's real binary. The lend prepends
+`~/.local/bin` to the login PATH, which is what puts the lent binary in front of
+the shim from then on — intended, and the reason the next launch probes
+*provisioned* and the transfer is paid once rather than forever.
+
+**This repo's own devcontainer feature bakes a shim.**
+`.devcontainer/claude-code/install.sh` installs `claude-shim`, so an image built
+from it does *not* meet the contract by itself: its first `dl` launch is lent a
+real `claude`, and only launches after that do nothing. Build the official layout
+into the image if you want the first launch free too.
+
+### What this deliberately does not do
+
+- **No per-tool transfer.** The lend is all-or-nothing — an image with a real `gh`
+  but a shimmed `claude` is sent both. Splitting the payload would save part of
+  one transfer, paid once per workspace, in exchange for a matrix of half-lent
+  states every later step would have to reason about. (The *network* install is
+  already per tool: each install guards itself with its own `command -v`.)
+- **No version sync.** A real `claude` already in the container is left alone
+  whatever its version. `dl` lends what is missing; it is not a package manager,
+  and keeping versions in step would mean deciding what to do when the container
+  is the newer one. The official binary self-updates in a long-lived workspace,
+  and rebuilding one re-provisions it from scratch. The single upgrade `dl` does
+  perform is replacing a shim with a real binary.
+
+### Turning it off
+
 ```bash
 DEVLAUNCH_NO_TOOLS=1 dl someone/repo
 ```
@@ -343,8 +424,8 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 | `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 --ls --size` | Add [what deleting each workspace would free](#how-much-disk-a-workspace-costs). Opt-in: it walks every file in the clone |
 | `dl --install` | Install shell completions |
+| `dl --prune [-y] [--force]` | Remove [the clone directories no workspace opens any more](#pruning-the-clones-nothing-opens) — and nothing else |
 | `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) |
 | `dl --refresh` | Refresh completion cache |
 | `dl --help, -h` | Show this help |
 | `dl --version` | Show version (an editable install also names the tree it runs from) |
@@ -441,6 +522,96 @@ directory yourself if you meant to: following the link would empty a directory
 you never named, and removing just the link would report a clean sweep while
 your clones sat on the other volume.
 
+### Pruning the clones nothing opens
+
+A workspace per branch means clone directories accumulate under the cache, and
+until now nothing removed them: measured on one host, **52 clone directories for
+17 live devpod workspaces — 37 of them attached to nothing, 4.00 GB, against
+7.86 GB still in use.** `--purge` is the wrong tool for that, being
+all-or-nothing: the only way to get the 4 GB back was to destroy the 7.86 GB
+too, and every bare cache with it.
+
+`dl --prune` removes exactly the clone directories no live workspace opens. It
+never deletes a devpod workspace, a container, an image or a volume, never
+touches a repo's `.bare` cache (0.08 GB for seven repos, and it is what makes
+the next clone of a repo fast), and never looks outside
+`<cache>/devlaunch/repos`. Every directory it finds is one of three things:
+
+- **a live workspace opens it** — kept, and named with the workspace that has
+  it. "Opens" means at *or under*: a workspace opened on a subdirectory of a
+  clone still needs the clone;
+- **nothing opens it** — removed, unless it holds work that exists nowhere else,
+  or `git` would not say what it holds. A clone a container wrote as another
+  user is unreadable rather than empty, and "cannot tell" is kept, not removed;
+- **`dl`'s records and devpod's disagree about it** — kept, always. This is
+  [#88](https://github.com/blooop/devlaunch/issues/88)'s shape. On that ticket's
+  host, 36 devpod workspaces out of 39 recorded a source folder that was gone or
+  was a config-only stub, while the real checkout sat beside it under a newer
+  naming scheme — so a perfectly healthy clone was opened by nobody, and the
+  stub was the only thing anything pointed at. `--prune` will not guess which
+  clone such a workspace needs: it keeps every clone of that repository and
+  names the record to go and fix. `--force` does not move any of them.
+
+Note that *every* directory two levels under `<cache>/devlaunch/repos` is a
+candidate — a stray directory somebody left there is looked at like any other.
+The cache is `dl`'s to manage; things that are not clones do not belong in it.
+But `git` cannot say what a directory that is not a repository holds, and
+"cannot say" is kept rather than removed, so clearing junk out of the cache
+takes `--force`. That is the same refusal a clone with a half-written `.git`
+gets, and deliberately so: telling the two apart would mean `--prune` forming
+its own opinion about a directory `dl <workspace> rm` already refuses on.
+
+```
+$ dl --prune
+Clone directories under /home/you/.cache/devlaunch/repos:
+
+Removing 2 that nothing references -- 1.4 GiB:
+  - /home/you/.cache/devlaunch/repos/blooop/bencher/bencher-test1-pipagito (1.1 GiB)
+  - /home/you/.cache/devlaunch/repos/blooop/devlaunch/devlaunch-t1-vebilote (317.0 MiB)
+
+Leaving 3:
+  - /home/you/.cache/devlaunch/repos/blooop/devlaunch/devlaunch-main-zovomobo: workspace devlaunch-main-zovomobo still opens it
+  - /home/you/.cache/devlaunch/repos/blooop/wayfinder/wayfinder-devlaunch-kilarabo: holds 2 unpushed commit(s) -- add --force to remove it anyway
+  - /home/you/.cache/devlaunch/repos/blooop/rockerc/rockerc-main-ludomane: devpod lists workspace rockerc-main-ludomane and sources it at /home/you/.cache/devlaunch/repos/blooop/rockerc/main; see devlaunch#88
+
+Dropping 12 record(s) of directories already gone.
+
+Are you sure? [y/N]
+```
+
+`-y` skips the question. **A clone holding uncommitted or unpushed work is kept
+and named**, in the same words [`dl <workspace> rm`](#cleaning-up-workspaces)
+refuses in — 13 of those 37 stale clones did, two of them with real unpushed
+commits, so this is load-bearing rather than a formality. `--force` promotes
+that one case and nothing else. Erring this way costs you a flag; erring the
+other way costs work that cannot be recovered.
+
+The sizes are the same *exclusive* bytes `dl --ls --size` reports, and they mean
+[the same thing](#how-much-disk-a-workspace-costs): what removing that directory
+would actually free, not what `du` would print. Where a walk could not read
+something the figure reads `≥` and so does the total, because a floor printed as
+a total is a cleanup tool telling you a directory is small when it is not.
+
+Directories that will not come away are named the same way [a purge names
+them](#when-part-of-the-cache-will-not-go), the rest still go, and the exit
+status is `1`.
+
+**Nothing here runs on its own.** A full scan measured 1017 ms on that host —
+about two warm launches — and it gets slower exactly as the cache gets fuller,
+so it is never on a launch path and never folded into `dl --ls`. Answering `n`
+*is* the read-only view; there is no separate flag for it. It costs one
+`devpod list` to build the plan and no `devpod status` at all, because whether a
+workspace is running has no bearing on whether a directory is opened by one. A
+run you say yes to pays a second `devpod list` before it removes anything, and
+classifies every directory again: a launch that finishes while the report is on
+screen registers a workspace for one of the directories in the plan, and that is
+the one thing the plan cannot be re-checked against from disk. The set you
+approved can shrink between the report and the act. It can never grow.
+
+It also drops the `metadata.json` records of directories that are already gone.
+That file was append-only in practice — 49 records for 17 live workspaces on the
+same host — and this is the first thing that prunes it.
+
 ### Cleaning up workspaces
 
 One workspace per branch means workspaces accumulate, and `--purge` is the wrong
@@ -636,6 +807,32 @@ dl blooop/devlaunch stop         # Stop workspace
 - **Fast Autocomplete**: Completion cache for ~3ms response time (vs ~700ms without cache)
 - **One Round-Trip Per Question**: every `devpod` call costs ~0.45s, far more than `dl` itself, so a command reads the workspace list at most once — and `dl <ws> -- <cmd>` skips the extra round-trip that names an interactive prompt, since a one-shot command has none
 
+## Measuring launch time
+
+Set `DEVLAUNCH_TIMING=1` and a `dl` command ends with one summary on stderr,
+naming each subprocess round trip and the total. Unset (or `0`) records nothing
+and prints nothing.
+
+```bash
+$ DEVLAUNCH_TIMING=1 dl myws -- true
+dl-timing: devpod status 0.412s
+dl-timing: devpod ssh 0.583s
+dl-timing: devpod ssh 1.102s
+dl-timing: total 2.201s (in-process, excluding interpreter startup)
+```
+
+For before/after numbers, `scripts/bench_launch.py` runs a command N times and
+reports the median — one command per side of a change:
+
+```bash
+python scripts/bench_launch.py -n 5 -- dl-next owner/repo -- true   # warm launch
+```
+
+(`pixi run bench -n 5 -- ...` in the devcontainer.) It reports no median if any
+run fails, so a broken launch cannot pass as a fast one. See `bench_launch.py
+--help` for `--before` — the per-run reset that makes a *cold* median cold —
+and for why its wall clock and `dl-timing: total` are not the same quantity.
+
 ## Worktree Backend
 
 For git repositories, devlaunch uses an efficient worktree backend by default:

{devlaunch-0.0.24 → devlaunch-0.0.26}/README.md

@@ -220,6 +220,7 @@ than the filesystem has actually done.
 | `dl <user/repo> restart` | Stop and start (no rebuild) |
 | `dl <user/repo> recreate` | Recreate container |
 | `dl <user/repo> reset` | Clean slate (remove all, recreate) |
+| `dl <user/repo> dotfiles` | Refresh dotfiles in the running workspace (`chezmoi update`) |
 | `dl <user/repo> -- <command>` | Run shell command in workspace (with a terminal, when `dl` has one) |
 
 ## Options
@@ -291,16 +292,96 @@ and `aid`. The repo's `devcontainer.json` does not have to provide them, and mos
 do not: `dl` launches arbitrary repos, so a guarantee that depended on the image
 would not be a guarantee.
 
-They are installed with `pixi global` on `devpod up`, and put on the PATH of a
-login shell through whichever of `~/.bash_profile`, `~/.bash_login` or `~/.profile`
-bash actually reads — it sources only the first of those that exists, so an image
-shipping a `~/.bash_profile` never reads `~/.profile`. A workspace that already has both is left alone —
-the check runs first, so the cost after the first launch is one round-trip and no
-network. If `pixi` is missing from the image, `dl` installs that too.
+### How they get there
+
+On `devpod up`, at most three round trips, each one earning the next.
+
+**1. A probe — the only trip a ready workspace ever pays.** The container reports
+what only it can know: whether both tools answer at all, where its `claude`
+resolves to, and where `~/.local/share/claude/versions` in its own home resolves
+to. It reports those and names no verdict; the host reads them, so "a real
+`claude`" is defined in exactly one place. The reading is one of three:
+
+- **provisioned** — `gh` answers on the login PATH and `claude` resolves to a
+  binary the official installer put in the versions directory. Nothing else
+  happens.
+- **lendable** — both names answer, but that `claude` is a shim or a wrapper.
+- **absent** — a tool is genuinely missing.
+
+**2. A lend, for *lendable* and *absent*.** `dl` streams its own `gh` and `claude`
+into the container as a tar over the `devpod ssh` channel it already holds — a
+local pipe, no network and no download. Nothing lands outside a staging directory
+until both binaries have been run there once, so a container that cannot execute
+them (a different libc, a different architecture) is left exactly as it was.
+
+**3. The network install, for *absent* only.** When the host had nothing to lend,
+or the lend was refused, `pixi global` installs both tools — and `pixi` itself
+first if the image has none. A *lendable* container never reaches this trip: it
+stops after the lend, or — when the host had nothing to lend — after the probe
+itself. A `claude` already answers there, and this install decides what to do
+with the same `command -v` that a shim satisfies, so the trip would install
+nothing.
+
+Tools reach the PATH of a login shell through whichever of `~/.bash_profile`,
+`~/.bash_login` or `~/.profile` bash actually reads — it sources only the first of
+those that exists, so an image shipping a `~/.bash_profile` never reads
+`~/.profile`.
 
 An install that fails costs the workspace its tools, not its launch: `dl` logs a
 warning and hands you the session anyway.
 
+### What to bake so a launch does no work at all
+
+To make every `dl` launch of an image stop at trip 1. The probe asks a **login**
+shell to resolve each name, so every bullet here is about what a login shell can
+find:
+
+- **`gh`** anywhere on the login PATH.
+- **`claude`** in the layout its official installer creates — the binary at
+  `~/.local/share/claude/versions/<version>`, a **direct child** of that
+  directory named for the version, with `~/.local/bin/claude` symlinked to it.
+  Nested any deeper — `versions/<version>/bin/claude`, the shape a downloader
+  parked there would take — is read as somebody else's tree that merely starts
+  with the official path, and does not count.
+- **`~/.local/bin` on the login PATH**. The symlink above is how `claude`
+  answers at all; a login shell that cannot find that directory reads the image
+  as *absent* however carefully the rest was baked, and it pays the full lend.
+  Ubuntu's stock `~/.profile` prepends `~/.local/bin` itself — but an image
+  shipping a `~/.bash_profile` never reads `~/.profile` (above), and then
+  nothing does.
+
+Nothing else counts as a `claude`, and that is the point. A *shim* — a small
+launcher that downloads the real binary the first time it is called — answers
+`command -v claude` exactly as the real thing does, while the workspace still
+owes a multi-hundred-megabyte download at the least convenient moment. So `dl`
+resolves the name rather than running it (running a shim *is* the download), reads
+a shim as *lendable*, and sends the host's real binary. The lend prepends
+`~/.local/bin` to the login PATH, which is what puts the lent binary in front of
+the shim from then on — intended, and the reason the next launch probes
+*provisioned* and the transfer is paid once rather than forever.
+
+**This repo's own devcontainer feature bakes a shim.**
+`.devcontainer/claude-code/install.sh` installs `claude-shim`, so an image built
+from it does *not* meet the contract by itself: its first `dl` launch is lent a
+real `claude`, and only launches after that do nothing. Build the official layout
+into the image if you want the first launch free too.
+
+### What this deliberately does not do
+
+- **No per-tool transfer.** The lend is all-or-nothing — an image with a real `gh`
+  but a shimmed `claude` is sent both. Splitting the payload would save part of
+  one transfer, paid once per workspace, in exchange for a matrix of half-lent
+  states every later step would have to reason about. (The *network* install is
+  already per tool: each install guards itself with its own `command -v`.)
+- **No version sync.** A real `claude` already in the container is left alone
+  whatever its version. `dl` lends what is missing; it is not a package manager,
+  and keeping versions in step would mean deciding what to do when the container
+  is the newer one. The official binary self-updates in a long-lived workspace,
+  and rebuilding one re-provisions it from scratch. The single upgrade `dl` does
+  perform is replacing a shim with a real binary.
+
+### Turning it off
+
 ```bash
 DEVLAUNCH_NO_TOOLS=1 dl someone/repo
 ```
@@ -321,8 +402,8 @@ existed — picks the tools up on its next `dl <workspace> restart`.
 | `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 --ls --size` | Add [what deleting each workspace would free](#how-much-disk-a-workspace-costs). Opt-in: it walks every file in the clone |
 | `dl --install` | Install shell completions |
+| `dl --prune [-y] [--force]` | Remove [the clone directories no workspace opens any more](#pruning-the-clones-nothing-opens) — and nothing else |
 | `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) |
 | `dl --refresh` | Refresh completion cache |
 | `dl --help, -h` | Show this help |
 | `dl --version` | Show version (an editable install also names the tree it runs from) |
@@ -419,6 +500,96 @@ directory yourself if you meant to: following the link would empty a directory
 you never named, and removing just the link would report a clean sweep while
 your clones sat on the other volume.
 
+### Pruning the clones nothing opens
+
+A workspace per branch means clone directories accumulate under the cache, and
+until now nothing removed them: measured on one host, **52 clone directories for
+17 live devpod workspaces — 37 of them attached to nothing, 4.00 GB, against
+7.86 GB still in use.** `--purge` is the wrong tool for that, being
+all-or-nothing: the only way to get the 4 GB back was to destroy the 7.86 GB
+too, and every bare cache with it.
+
+`dl --prune` removes exactly the clone directories no live workspace opens. It
+never deletes a devpod workspace, a container, an image or a volume, never
+touches a repo's `.bare` cache (0.08 GB for seven repos, and it is what makes
+the next clone of a repo fast), and never looks outside
+`<cache>/devlaunch/repos`. Every directory it finds is one of three things:
+
+- **a live workspace opens it** — kept, and named with the workspace that has
+  it. "Opens" means at *or under*: a workspace opened on a subdirectory of a
+  clone still needs the clone;
+- **nothing opens it** — removed, unless it holds work that exists nowhere else,
+  or `git` would not say what it holds. A clone a container wrote as another
+  user is unreadable rather than empty, and "cannot tell" is kept, not removed;
+- **`dl`'s records and devpod's disagree about it** — kept, always. This is
+  [#88](https://github.com/blooop/devlaunch/issues/88)'s shape. On that ticket's
+  host, 36 devpod workspaces out of 39 recorded a source folder that was gone or
+  was a config-only stub, while the real checkout sat beside it under a newer
+  naming scheme — so a perfectly healthy clone was opened by nobody, and the
+  stub was the only thing anything pointed at. `--prune` will not guess which
+  clone such a workspace needs: it keeps every clone of that repository and
+  names the record to go and fix. `--force` does not move any of them.
+
+Note that *every* directory two levels under `<cache>/devlaunch/repos` is a
+candidate — a stray directory somebody left there is looked at like any other.
+The cache is `dl`'s to manage; things that are not clones do not belong in it.
+But `git` cannot say what a directory that is not a repository holds, and
+"cannot say" is kept rather than removed, so clearing junk out of the cache
+takes `--force`. That is the same refusal a clone with a half-written `.git`
+gets, and deliberately so: telling the two apart would mean `--prune` forming
+its own opinion about a directory `dl <workspace> rm` already refuses on.
+
+```
+$ dl --prune
+Clone directories under /home/you/.cache/devlaunch/repos:
+
+Removing 2 that nothing references -- 1.4 GiB:
+  - /home/you/.cache/devlaunch/repos/blooop/bencher/bencher-test1-pipagito (1.1 GiB)
+  - /home/you/.cache/devlaunch/repos/blooop/devlaunch/devlaunch-t1-vebilote (317.0 MiB)
+
+Leaving 3:
+  - /home/you/.cache/devlaunch/repos/blooop/devlaunch/devlaunch-main-zovomobo: workspace devlaunch-main-zovomobo still opens it
+  - /home/you/.cache/devlaunch/repos/blooop/wayfinder/wayfinder-devlaunch-kilarabo: holds 2 unpushed commit(s) -- add --force to remove it anyway
+  - /home/you/.cache/devlaunch/repos/blooop/rockerc/rockerc-main-ludomane: devpod lists workspace rockerc-main-ludomane and sources it at /home/you/.cache/devlaunch/repos/blooop/rockerc/main; see devlaunch#88
+
+Dropping 12 record(s) of directories already gone.
+
+Are you sure? [y/N]
+```
+
+`-y` skips the question. **A clone holding uncommitted or unpushed work is kept
+and named**, in the same words [`dl <workspace> rm`](#cleaning-up-workspaces)
+refuses in — 13 of those 37 stale clones did, two of them with real unpushed
+commits, so this is load-bearing rather than a formality. `--force` promotes
+that one case and nothing else. Erring this way costs you a flag; erring the
+other way costs work that cannot be recovered.
+
+The sizes are the same *exclusive* bytes `dl --ls --size` reports, and they mean
+[the same thing](#how-much-disk-a-workspace-costs): what removing that directory
+would actually free, not what `du` would print. Where a walk could not read
+something the figure reads `≥` and so does the total, because a floor printed as
+a total is a cleanup tool telling you a directory is small when it is not.
+
+Directories that will not come away are named the same way [a purge names
+them](#when-part-of-the-cache-will-not-go), the rest still go, and the exit
+status is `1`.
+
+**Nothing here runs on its own.** A full scan measured 1017 ms on that host —
+about two warm launches — and it gets slower exactly as the cache gets fuller,
+so it is never on a launch path and never folded into `dl --ls`. Answering `n`
+*is* the read-only view; there is no separate flag for it. It costs one
+`devpod list` to build the plan and no `devpod status` at all, because whether a
+workspace is running has no bearing on whether a directory is opened by one. A
+run you say yes to pays a second `devpod list` before it removes anything, and
+classifies every directory again: a launch that finishes while the report is on
+screen registers a workspace for one of the directories in the plan, and that is
+the one thing the plan cannot be re-checked against from disk. The set you
+approved can shrink between the report and the act. It can never grow.
+
+It also drops the `metadata.json` records of directories that are already gone.
+That file was append-only in practice — 49 records for 17 live workspaces on the
+same host — and this is the first thing that prunes it.
+
 ### Cleaning up workspaces
 
 One workspace per branch means workspaces accumulate, and `--purge` is the wrong
@@ -614,6 +785,32 @@ dl blooop/devlaunch stop         # Stop workspace
 - **Fast Autocomplete**: Completion cache for ~3ms response time (vs ~700ms without cache)
 - **One Round-Trip Per Question**: every `devpod` call costs ~0.45s, far more than `dl` itself, so a command reads the workspace list at most once — and `dl <ws> -- <cmd>` skips the extra round-trip that names an interactive prompt, since a one-shot command has none
 
+## Measuring launch time
+
+Set `DEVLAUNCH_TIMING=1` and a `dl` command ends with one summary on stderr,
+naming each subprocess round trip and the total. Unset (or `0`) records nothing
+and prints nothing.
+
+```bash
+$ DEVLAUNCH_TIMING=1 dl myws -- true
+dl-timing: devpod status 0.412s
+dl-timing: devpod ssh 0.583s
+dl-timing: devpod ssh 1.102s
+dl-timing: total 2.201s (in-process, excluding interpreter startup)
+```
+
+For before/after numbers, `scripts/bench_launch.py` runs a command N times and
+reports the median — one command per side of a change:
+
+```bash
+python scripts/bench_launch.py -n 5 -- dl-next owner/repo -- true   # warm launch
+```
+
+(`pixi run bench -n 5 -- ...` in the devcontainer.) It reports no median if any
+run fails, so a broken launch cannot pass as a fast one. See `bench_launch.py
+--help` for `--before` — the per-run reset that makes a *cold* median cold —
+and for why its wall clock and `dl-timing: total` are not the same quantity.
+
 ## Worktree Backend
 
 For git repositories, devlaunch uses an efficient worktree backend by default:

{devlaunch-0.0.24 → devlaunch-0.0.26}/devlaunch/completions/dl.bash

@@ -61,7 +61,7 @@ _dl_completion() {
     fi
 
     # Workspace subcommands
-    local ws_cmds="up stop rm code restart recreate reset --"
+    local ws_cmds="up stop rm code restart recreate reset dotfiles --"
 
     # Options that take a value; a variant name or a path follows them.
     local value_opts="--devcontainer"

{devlaunch-0.0.24 → devlaunch-0.0.26}/devlaunch/disk_usage.py

@@ -58,7 +58,7 @@ import os
 import stat
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, List, NoReturn, Tuple, Union
+from typing import Any, Dict, Iterable, List, NoReturn, Tuple, Union
 
 # st_blocks is counted in 512-byte units by POSIX, whatever the filesystem's own
 # block size is.
@@ -230,6 +230,37 @@ def known_bytes(usage: DiskUsage) -> int:
     _unhandled_usage(usage)
 
 
+def _unreadable_in(usage: DiskUsage) -> Tuple[Path, ...]:
+    """The doors this usage could not open -- none, for a complete walk."""
+    if isinstance(usage, Measured):
+        return ()
+    if isinstance(usage, PartlyUnreadable):
+        return usage.unreadable
+    _unhandled_usage(usage)
+
+
+def total_usage(usages: Iterable[DiskUsage]) -> DiskUsage:
+    """What removing all of *usages*' trees together would free.
+
+    A sum with one floor in it is a floor, and this returns the arm that says
+    so. That is the whole reason a total lives here rather than in the caller:
+    adding :func:`known_bytes` up gives an integer that has lost which kind of
+    answer it is, and an integer printed as a size is a floor read as a total --
+    the one mistake every other function in this module is shaped to prevent.
+
+    Which bytes these are, and why they do not add up to the disk a cache holds,
+    is the module docstring's business and is not restated here.
+    """
+    known = 0
+    unreadable: List[Path] = []
+    for usage in usages:
+        known += known_bytes(usage)
+        unreadable.extend(_unreadable_in(usage))
+    if unreadable:
+        return PartlyUnreadable(known, tuple(unreadable))
+    return Measured(known)
+
+
 def usage_as_json(usage: DiskUsage) -> Dict[str, Any]:
     """How a usage reads to a tool: one key, and the key says which kind it is.