Skip to content

Explain blocking changes during refresh#840

Open
tlm wants to merge 4 commits into
wsp-960-start-error-outputfrom
wsp-960-refresh-error-output
Open

Explain blocking changes during refresh#840
tlm wants to merge 4 commits into
wsp-960-start-error-outputfrom
wsp-960-refresh-error-output

Conversation

@tlm

@tlm tlm commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Description

This PR is stacked on top of #831.

It builds on the structured change-conflict plumbing from
#829 and applies the same
user-facing treatment to workshop refresh.

It also follows the refresh output style from
#828, so refresh failures point users
directly to the relevant task details and recovery commands.

Previously, if workshop refresh was blocked by a paused refresh, the CLI
surfaced a generic error and then reported that refresh was aborted:

error: cannot refresh "dev": waiting on error
"dev" refresh aborted

After this change, workshop refresh explains that the existing refresh is
paused, shows the task details command, and gives the abort or continue recovery
commands:

error: cannot refresh "dev"; paused
To view details: "workshop tasks 29"

To abort and undo: "workshop refresh --abort dev"
Otherwise, resolve the error, then run "workshop refresh --continue dev"

For non-refresh conflicts, the message identifies the blocking change kind:

error: cannot refresh "dev": change launch is in progress
To view details: "workshop tasks 30"

The change keeps the same layering as the stop and start conflict work:

  • workshopstate.RefreshManifests preserves typed change-conflict details when
    a workshop is pending or waiting on another change.
  • The daemon API returns structured change-conflict responses.
  • The CLI formats refresh-specific guidance from client.ChangeConflictError.

Validation run:

go test ./cmd/workshop -check.f TestRefresh.*Conflict
go test ./internal/overlord/workshopstate -check.f TestRefreshManifestsWaitingReturnsChangeConflict
go test ./internal/daemon -check.f 'TestRefresh(ConflictChange|WorkshopChangeConflict)'
go test ./cmd/workshop ./internal/overlord/workshopstate ./internal/daemon
/tmp/spread/spread-bin tests/main/refresh-abort

Self-review quick check

  • Make decisions that cost a lot to reverse explicit in the PR description.
  • Avoid nested conditions.
  • Delete dead code and redundant comments.
  • Normalise symmetries by sticking to doing identical things identically.
  • Check that coupled code elements, files, and directories are adjacent. For example, test data is stored as close as possible to a test.
  • Put variable declaration and initialisation together.
  • Divide large expressions into digestable and self-explanatory ones. Use multiple variables if required.
  • Put a blank line between two logically different chunks of code.
  • Follow the style guide for new error messages.

Docs

Procedure:

  • I have checked and added or updated relevant documentation.
  • I have checked and added or updated relevant release notes.
  • I have included the technical author in the review.

Content:

  • Headings and titles accurately describe the content.
  • New and updated pages include correct metadata.
  • Documentation tests are added or updated where applicable (for tutorial/ and how-to/ sections).
  • Documentation follows the style guide.
  • If needed, docs/.coverage.yaml updated, coverage tags added (.. artefact).

Or:

  • I confirm the PR has no implications for documentation.

@tlm tlm self-assigned this Jun 9, 2026
@tlm tlm force-pushed the wsp-960-start-error-output branch from 47a1e69 to 0a223b2 Compare June 10, 2026 00:17
tlm added 4 commits June 10, 2026 00:19
Show clearer workshop refresh errors when another change is blocking the
operation, including task details and refresh recovery commands when the
blocking change is a paused refresh.
Return the blocking change conflict from refresh manifest loading when a workshop is pending or waiting on another change, so callers can surface the change kind, status, and task ID instead of a generic health error.
Add API coverage for refresh requests blocked by a waiting refresh, verifying the daemon returns a structured change-conflict error with the blocking change details.
Assert that a refresh blocked by a paused refresh shows the task details and abort or continue recovery commands in the refresh-abort spread test.
@tlm tlm force-pushed the wsp-960-refresh-error-output branch from 188cb3b to e16d996 Compare June 10, 2026 00:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant