list_workspaces reports empty when it merely failed to read

[blooop]

Question

dl still reports "no workspaces" when it merely failed to read them. Fix the
production copy of the defect a dev task just stopped making.

Graduated from PR #118's review,
which found this while checking that the PR did what it claimed. It is the
sharpest kind of finding: the PR body describes eliminating exactly this shape,
and it eliminated it in a dev task and a test helper while production keeps doing
it.

devlaunch/dl.py:930-937 — list_workspaces() returns [] for both a failed
devpod list and an unparseable one. Demonstrated live by the reviewer. Callers
cannot distinguish "devpod says there are none" from "devpod could not be asked",
and they do not try.

The new devlaunch/devpod_provider.py:18-22 argues the opposite in its own
comments — that unreadable is not empty — and models it with an
UnreadableProviderList exception. So the repo now holds both positions at once,
in the same package, one of them in the code users actually run.

Why it matters beyond tidiness. purge_all_data() iterates
list_workspaces(). A silent [] there means a purge that quietly does nothing
looks identical to a purge that had nothing to do. Elsewhere the same [] can
read as "this workspace does not exist yet", which is the wrong branch to take
when the truth is "I could not tell".

Principle 3 is the whole ticket. Two outcomes are being collapsed into one
representation. Make the distinction one the type system states rather than one a
caller has to remember — and note that devpod_provider.py has already chosen a
shape for this in this very repo, so consistency (the map's tiebreak) points at
reusing it rather than inventing a second spelling. Run
/constructive-modeling on whatever you land.

Also fold in the smaller sibling the same review named: ensure_provider's
add-failure path raises a bare RuntimeError (devpod_provider.py:83) and omits
capture_output, so its message carries no stderr while its neighbour at :65
does — and main()'s except (UnreadableProviderList, RuntimeError) (:108) is
redundant, since the first subclasses the second, so it will swallow unrelated
RuntimeErrors.

This is a wayfinder:build ticket: go through /tdd.

Test-first. The red test is a devpod list that fails, and a caller that must
not conclude "empty". Both failure modes want covering — non-zero rc and
well-formed-but-unparseable output — because they are the two the current code
merges.

Relation to #107. That
ticket teaches --purge which workspaces are devlaunch's. This one is about
whether the list can be trusted at all. They meet in purge_all_data(), and #107
should be able to assume a trustworthy list — but they are separable and neither
blocks the other. Whichever lands second should not re-litigate the first.

[blooop]

handoff

Parked, not blocked — this ticket is actionable right now and nothing in the
tree prevents it. I am stopping here deliberately.

Where we are. The map's decision phase is complete (all nine decision tickets
closed) and three PRs are open and waiting on a human merge:
#106 (approved),
#118 (approved on content, held
behind #106 by merge order), #119
(approved). Four tickets — #107, #109, #114, #116 — unblock on those merges.

Why park rather than build. The map's remaining value is gated on merges, not
on more parallel branches. A fourth unmerged PR adds review burden and conflict
surface without moving anything closer to the destination, and this ticket touches
devlaunch/dl.py, which is the one file none of the three open PRs modify — so
its value is highest after the queue drains, when it can be built against a tree
that reflects the decisions rather than against a snapshot that predates them.

The open thread. The finding itself is settled and needs no more
investigation: dl.py:930-937 collapses a failed and an unparseable
devpod list into the same [], demonstrated live by PR #118's reviewer, while
devpod_provider.py:18-22 argues the opposite in the same package.

First move on resume. Read this ticket's body — it is complete and names the
shape to reuse (UnreadableProviderList), the two failure modes the red tests
must separate, and the relationship to #107. Then go straight to /tdd. Check
first whether #118 has merged, since it introduced the exception type this ticket
should reuse rather than re-invent; if it has not, decide whether to depend on it
or define the distinction independently and reconcile later.

[blooop]

breadcrumb: unparked — the merge queue this was parked behind has drained (#106, #118, #119 all merged; main at 0.0.16, CI green). The reason for parking is gone, and #107 now sequences behind this ticket, so it is on the critical path rather than adjacent to it.

[blooop]

breadcrumb: picked this up. What I am building: the workspace listing stops being able to say [] when it means "I could not read devpod". Three seams, all pre-agreed by the ticket:

1. The listing read itself — the two failure modes it currently merges get separate red tests: devpod exiting non-zero, and devpod exiting zero with output that is not a readable listing. Neither may come back as "no workspaces". A listing that reads fine and is empty still comes back empty.
2. Purge — an unreadable listing must stop the purge before it deletes anything, rather than printing that there was nothing to do. This is the caller the ticket names as the reason it matters.
3. The provider guard's two siblings — the add-failure path gets a type and a message that carries devpod's stderr, and the CLI stops catching a base class broad enough to swallow failures it knows nothing about.

Verified on metal first, because the whole fix turns on it: devpod with an empty home answers [], not nothing at all. So "exited zero and said nothing" is genuinely unreadable rather than a legitimate way to say empty, and the fix can treat it as such without inventing a failure devpod does not have.

[blooop]

breadcrumb: the type is an exception, UnreadableWorkspaceList, and it reads deliberately like the provider guard's: same name pattern, same docstring saying what it is not, same split between "ask devpod" and "parse what devpod said" so both halves of the failure land in one place.

I did weigh the other candidate, a result value with an "unreadable" arm that every caller opens. It loses on the map's own principle 5: six of the seven readers of the workspace list have nothing to do with an unreadable arm — a completion helper, a fuzzy picker, a table printer. Making each one open the box and re-raise buys six new branches and no new decision. The exception moves the obligation to the one place that already owns this shape of failure: the CLI's single handler, which has been the home of "devpod is not installed" since that landed.

One deviation from the provider guard, and it is on purpose. The provider exception subclasses RuntimeError; this one subclasses Exception, because the CLI catches RuntimeError broadly wherever a flaky command should degrade rather than abort, and an answer it could not read is exactly the thing that must not degrade. The codebase already argues this in prose for the missing-binary type, which is not a RuntimeError for the same reason. Rather than leave two rules, I moved the provider exception off RuntimeError too — which also dissolves the redundant-handler sibling at its root instead of patching the tuple.

[blooop]

breadcrumb: #122 is open, CI green on all four Python versions. One slice: the workspace listing raises rather than answering [] when it could not be read, handled once beside the missing-binary handler, with the provider guard's two siblings folded in. Both failure modes were red first, and both were then driven end to end against a stub devpod with the cache scoped away from the real one — the purge path now stops and quotes devpod instead of removing the cache and reporting that there was nothing to do.

Three existing tests were the defect written down as assertions; they now assert the opposite with their original intent intact. No release files touched, since several bumps are in flight — the changelog prose is the last section of the PR body for a merge train to lift in.

Nothing filtered by owner, so the ownership question is untouched and the seam is the one it wanted: the purge still reads the listing itself and now gets back either a list devpod actually gave or an exception, so narrowing "every workspace" to "devlaunch's" is one filter in one place against a list that can be trusted. The listing function says as much in its own docstring so the two questions stay separate.

Ready for /review. Read-only devpod list on the host is unchanged before and after.

[blooop]

breadcrumb: build stage complete → in review. PR #122 green at 483d637d2cda76489e82c5052670f9d40ba676dc, runs present for the SHA.

Two things the reviewer needs to weigh rather than accept:

1. A deliberate deviation that edits code Two defects that break the dev tasks and the e2e suite before dind is involved #118 landed an hour ago. The new UnreadableWorkspaceList subclasses Exception, not RuntimeError — the argument being that dl catches RuntimeError broadly wherever a flaky command should degrade, which is exactly what an unreadable answer must not do. To avoid two rules in one package the agent also moved UnreadableProviderList off RuntimeError, which dissolves the redundant-except-tuple sibling at its root rather than patching it. Defensible, and arguably the right call — but it is scope growth into freshly-merged code and deserves a real look.
2. An exception was chosen over a result type with an Unreadable arm, on the grounds that six of the seven readers have no action for that arm, so the sum type would buy six re-raise branches and no decisions. Principle 3 usually pushes the other way; judge whether the exception really is the smaller honest model here.

[blooop]

breadcrumb: review posted on #122 — Comment / approve in substance, nothing blocking. Both failure modes reproduced by mutation and driven end to end at merge-base and head against a stub devpod; the metal claim (devpod list --output json prints [] for an empty DEVPOD_HOME) re-verified on v0.26.1; purge now refuses and quotes devpod instead of removing the cache and reporting success. Both judgement calls go the author's way: the re-parenting off RuntimeError has a blast radius of one module (all seven except RuntimeError sites in the tree wrap git/workspace_up, never a listing), and the exception over a sum type is principled — none of the seven readers has a local action for an unreadable arm. Four non-blocking findings, strongest first: dl --install regressed from degrading to hard-failing when devpod is unreadable (the one reader that did have an action, and it contradicts the proposed changelog's "Nothing about how you install or run dl changes"); the rc-path error message interpolates raw multi-line stderr where the parse path uses !r, breaking the one-line invariant the file states for itself; the isinstance(parsed, list) guard has a surviving mutant (its test passes for the wrong reason); and the silence case gets a message that reads as a parse bug. Changelog prose is accurate and in voice apart from that opening sentence. devpod list unchanged, 6 workspaces before and after.

[blooop]

breadcrumb: review verdict — approve in substance, but one behavioural regression found that I am treating as fix-before-merge rather than as the reviewer's "nothing blocking": dl --install went from degrading to hard-failing when the listing is unreadable, because update_completion_cache() reads the list and --install calls it first. Driven end to end with a stub devpod exiting 1 — merge-base wrote the completions and returned 0; PR head writes nothing and returns 1. It also contradicts the PR's own changelog line "Nothing about how you install or run dl changes".

That is the bill for judgement call B: the argument was no reader has an action, and update_completion_cache did have one — the exception let it default to abort unchosen. Ruling stands that the exception is a principled choice over a sum type, but the reasoning needed this correction.

Judgement call A (re-parenting off RuntimeError) verified right: all seven except RuntimeError sites wrap repo/branch/workspace/git calls, none wraps a listing, and exactly one thing stops being caught — the stated goal, with a test pinning it.

[blooop]

breadcrumb: review findings addressed on #122, pushed at fd1cd7bd3e8bb8cb46cfd905923b174f9e5a0315. CI green on all four Python versions with runs present for the new head SHA; PR left open and unmerged.

S1, the one treated as fix-before-merge rather than the reviewer's "non-blocking". dl --install had regressed from degrading to hard-failing when the workspace listing is unreadable, because update_completion_cache() reads the listing and --install calls it first. Fixed by catching at that one call site and completing on what is still visible — the smaller of the two options the review named, and the right one rather than merely the cheapest: completion generation is the only reader whose subject is not the workspace list. It collects four things, and repos, owners and branches all come off local disk without asking devpod anything, so an unreachable devpod costs it the workspace names and nothing else. The failure is logged rather than swallowed, because dl --refresh prints the count it got and zero-because-we-could-not-ask must not read as zero-because-there-are-none.

Three tests red first against 483d637, then driven end to end against a stub devpod exiting 1, from a neutral cwd, with the merge-base extracted to its own tree by git archive so neither copy could shadow the other (both interpreters printed their devlaunch.dl.__file__ first). dl --install is back to rc 0 with the completion script and source block written, and dl --completion-data back to emitting {"workspaces": [], "repos": ["blooop/devlaunch"], …} — byte-equivalent to the merge-base — while dl --ls and dl --purge still refuse, which is the change the ticket asked for. The changelog's opening line "Nothing about how you install or run dl changes" is therefore true again rather than needing a caveat; the PR body's proposed entry gains a bullet spelling the completion carve-out out.

S2 — !r on the rc path, and in all three places the package quotes a failing devpod rather than only the one named, so the one-line rule the file states above DEVPOD_MISSING_MESSAGE has one home. Pinned by a test that feeds three-line stderr and asserts both that the message is one line and that devpod's words survived into it.

S3 — the surviving isinstance(parsed, list) mutant is dead. The shape test now asserts the message it names its branch after, and is parametrised over the scalar shapes the per-entry guard cannot rescue. Re-ran the mutation on this head: 0 failures → 4, full suite otherwise green, mutation reverted.

S4/S5 — silence gets its own branch in parse_workspaces and says it was silence instead of not JSON: ''; the README documents the new exit 1 beside the existing 127, including the completion carve-out.

The instruction that had not been followed literally — /constructive-modeling — was run on the landed shape, and its output posted in full on the PR rather than summarised. Verdict: no change, with one cost accepted explicitly and one real finding deferred. The cost: an exception is a sum type the compiler will not make you handle, and ty runs in CI so a list[Workspace] | UnreadableListing with assert_never would be enforced — that is exactly the enforcement missing when update_completion_cache defaulted to abort. Declined anyway under principle 4: 7 unwrap sites, 6 of them immediate re-raises, to enforce a decision that has been wrong once and is now pinned by three tests. The deferred finding is Workspace.source_type (dl.py:701-732) — a tag beside a parallel field with a sentinel "unknown" arm that stuffs str(dict) into a field the other arms fill with a path or a URL, and an if/elif at dl.py:810-814 with no else that drops it silently. Pre-existing, 5 call sites, orthogonal to this ticket (it is about what a workspace is, not whether the list of them can be believed) — worth its own ticket.

1002 passed (was 994), lint/type/pylint clean. e2e never run, --purge never pointed at real state, no devpod delete. Host devpod list unchanged: 6 workspaces before and after. One thing to note rather than hide: ~/.config/devlaunch/completions.sh was written at 12:53 today by something that is not this session — every probe here scoped DEVLAUNCH_COMPLETION_FILE to a scratch path under env -i, and the last of them ran half an hour earlier. Its contents are byte-identical to what a dl --install writes, so there is no drift; flagging it only because completion.py:33 hardcodes ~/.config and ignores XDG_CONFIG_HOME, which is a real trap for anyone probing this path and arguably its own small ticket.

[blooop]

Merged in #122 and shipped in v0.0.18.