workspaces 0.1.14 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 160b209187a95a674c6ce4936b4b2863ed5893ac8331f1f0345d550cf09f2f2d
-  data.tar.gz: ba7ef0dd3ed8c913ea29683f641c1d4ac314ee15a1c201dd45634d45a8a980bc
+  metadata.gz: a68a635327e6a8f69c8c7d29f881e5bb6eb12e57d66e1dff7ea31d8e3c8dc9ab
+  data.tar.gz: 7306dff7993e982666f948a81a2131b7b6f165dfa61b4a729ae093b6feb7583e
 SHA512:
-  metadata.gz: 978a8f06eda4d6d9c0c443499f1cf28f41c33800b3394b40fb56dd8771e0f1283001a4e24effcb3f7c52563023a18e1f48bfe884f97bd255642ff9379b9ea095
-  data.tar.gz: 8162b0c59925b414a1af0ff511fcc6bee2d79f83bb42d452614ef68f79c7ee52e42cb89531c21c5e77b29bc76b76cdfea4f4b5fff73fff2217b49217a0321a2c
+  metadata.gz: f2b165a4f127e77c942338f0ae5bcfc5d0f9ad016ea69bac7282dfa0dacc4158c860269d2ccd98eae794a56381d519bc192be6d0d44c2bb03f24060800464ed0
+  data.tar.gz: 8e4a2a00f375c70bb10d16512ad11e8463357db5074061e682246ec2972eba108620118b29549534e8636a220efa6bd894b1e9516d4a8ffecf8f18ac960828a4

data/DESIGN.md

@@ -57,10 +57,11 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
   - `busy`: "Setting things up…", with the current step as a quiet line and the elapsed time. Technical details open so progress and the log can be watched.
   - `ready`: "Your workspace is ready" with a large **Open workspace** button. Everything else is collapsed.
   - `stopped`: "Your workspace is paused" with a large **Start workspace** button.
-  - `error`/`interrupted`: a plain "Something didn't go to plan" with a large **Retry** button, the error shown, and technical details open.
+  - `error`/`interrupted`: a plain "Something didn't go to plan" with a large **Retry failed step** button (**Continue setup** after an interruption) that names the step in the summary, a subtle **Re-run all steps** beside it, the error shown, and technical details open. When the recorded steps cannot be resumed, the single **Retry** of the earlier design is shown instead.
   - `unknown`: a minimal view with technical details open.
 - **Disclosure behavior**: the server renders the initial open state and the polling script re-applies it from `presentation.open`, but only when the state changes. A section the user opened or closed is left alone on later polls. Sections that are not meaningful in a state are hidden, never shown disabled.
-- **Action buttons**: start, prepare/rebuild, restart server, stop server, and refresh
+- **Per-step re-run controls**: inside each step's accordion, small subtle **Re-run this step** and **Re-run from here** forms aimed at `/workspaces/ID/resume?only=KEY` and `?from=KEY`. The server decides which appear (`presentation.resume.step_modes`), so the page never offers something that would be refused; they are hidden while a run is in progress and are disabled with the other controls while busy.
+- **Action buttons**: start, prepare/rebuild, restart server, stop server, retry failed step, and refresh
 - **Open workspace**: success-styled link available when the server is ready
 - **Lifecycle controls**: hidden while busy (see state machine); helper text distinguishes rebuilding from server-only restart
 - **Step logs (GitHub Actions style)**: setup output is split by recipe step. Each step is a `<details>` row with a status icon (ring, pulsing ring, check or cross), its name, how long it took and a chevron; opening it shows only that step's output. A step that is running or has failed starts open and a completed or waiting one starts closed. The script updates rows in place by step id, and applies the open preference only when a step's state changes, so a row the reader toggled is never reopened or reclosed and what they are reading is never rebuilt.

data/README.md

@@ -98,7 +98,7 @@ the percentage, the elapsed time and, once there is history, an estimate of what
 Every finished run is appended to `build-history.jsonl` in the Workspaces home, one JSON
 object per line, shared by all workspaces of the project. It is written quietly and a failure
 to write it never affects the build. Each record has the time, workspace, operation
-(`prepare` or `restart`), result (`complete` or `failed`), `total_seconds`, the Workspaces
+(`prepare`, `restart` or `resume`), result (`complete` or `failed`), `total_seconds`, the Workspaces
 version, and each step's id, state and seconds. To see which step is getting slower:
 
 ```sh
@@ -142,6 +142,35 @@ provides `WORKSPACE_RUN_ID`). The runner also supplies `WORKSPACE_URL` and
 `WORKSPACE_HOST` for applications that need browser-facing URLs and host settings.
 `serve` does **not** start workspace backends; use `start` or `restart` for those.
 
+### Re-running part of a run
+
+When a run fails, or is interrupted, you do not have to start over. `resume` continues from the
+first step that did not finish and keeps every earlier step's state, time and log:
+
+```sh
+bin/workspaces resume ID                  # retry from the first unfinished step
+bin/workspaces resume ID --from STEP      # re-run STEP and every step after it
+bin/workspaces resume ID --only STEP      # re-run exactly one step
+```
+
+The dashboard offers the same: **Retry failed step** (or **Continue setup** after an
+interruption) with **Re-run all steps** beside it, and, inside each step, **Re-run this step**
+and **Re-run from here** where they are allowed. `POST /workspaces/ID/resume` takes optional
+`from=STEP` or `only=STEP` query parameters.
+
+A failed run stops the server, so a failure at or after the `background: true` step retries from
+that step, exactly like a restart: the server is started again with a fresh `WORKSPACE_RUN_ID`
+and readiness is checked against it. A failure before the server step retries that step and
+everything after it. Re-running steps *after* the server step, on a workspace whose server is
+still up, reuses that server's port and `WORKSPACE_RUN_ID`, and leaves it running even if
+the step fails.
+
+A re-run never leaves an unfinished step behind (`--from` cannot skip one, `--only` needs every
+other step finished), so a successful one always means a complete workspace. It is refused, in
+plain words, when `.workspaces.yml`'s steps no longer match the ones recorded, when the server
+step is asked for on its own, or when a step after the server is asked for and the server is not
+running. The build history records only the steps that re-ran, with operation `resume`.
+
 The `/workspaces` dashboard lists each managed workspace's setup status, whether its
 backend is running, creation time, and last backend startup. On a workspace's detail
 page, the Danger Zone lets an operator delete that one workspace after typing its

data/lib/workspaces/backend.rb

@@ -25,6 +25,17 @@ module Workspaces
       @state.get(workspace_id)&.fetch('port', nil)
     end
 
+    # The WORKSPACE_RUN_ID the current server was started with. A step that runs after the server
+    # (readiness) has to see the same value, so it is kept while the server lives.
+    def run_id
+      @state.get(workspace_id)&.fetch('run_id', nil)
+    end
+
+    # True only for a server that can be checked by a later step on its own: alive, with its token.
+    def resumable?
+      !!running? && !run_id.to_s.empty?
+    end
+
     def reserve!
       @state.transaction do |data|
         taken = data.values.filter_map { |entry| entry['port'] }
@@ -54,7 +65,7 @@ module Workspaces
       entry = @state.get(workspace_id) || {}
       terminate(entry['pid'], group: entry['process_group']) if entry['pid']
       @state.transaction do |data|
-        %w(pid port process_group).each { |key| data[workspace_id]&.delete(key) }
+        %w(pid port process_group run_id).each { |key| data[workspace_id]&.delete(key) }
       end
     end
 

data/lib/workspaces/cli.rb

@@ -14,7 +14,7 @@ module Workspaces
     COMMANDS = {
       'serve' => :serve, 'create' => :create, 'list' => :list, 'show' => :show,
       'start' => :lifecycle, 'prepare' => :lifecycle, 'restart' => :lifecycle,
-      'stop' => :stop, 'remove' => :remove, 'help' => :help
+      'stop' => :stop, 'remove' => :remove, 'resume' => :resume, 'help' => :help
     }.freeze
     def self.run(argv)
       new.run(argv.dup)
@@ -50,6 +50,7 @@ module Workspaces
       options = {}
       OptionParser.new do |parser|
         parse_common_options(parser, options)
+        parser.on('--only STEP') { |value| options[:only] = value } if command == 'resume'
         parser.on('--preset NAME') { |value| options[:preset] = value } if %w(create start prepare restart).include?(command)
         if %w(create start prepare restart).include?(command)
           parser.on('--set NAME=VALUE') do |value|
@@ -157,6 +158,24 @@ module Workspaces
       coordinator.wait(id)
     end
 
+    # Re-runs part of the last run: from the first unfinished step by default, from a named step
+    # onward with --from, or exactly one step with --only. Finished steps keep their time and log.
+    def resume(id, options)
+      raise ArgumentError, 'Choose either --from or --only, not both' if options[:from] && options[:only]
+      raise ArgumentError, 'resume needs a workspace ID' unless id
+
+      mode = options[:only] ? :only : (options[:from] ? :from : :retry)
+      action = proc do
+        started = coordinator.rerun(id, mode: mode, key: options[:only] || options[:from])
+        raise ArgumentError, 'Workspace is busy; inspect it with show --json' if !started && coordinator.snapshot(id)['active']
+
+        coordinator.wait(id)
+      end
+      result = options[:json] ? with_stdout_on_stderr(&action) : action.call
+      emit(result, options)
+      raise ArgumentError, result['last_error'] if result['status'] == 'error'
+    end
+
     def stop(id, options)
       registry.with_lock(id) do
         Backend.new(id).stop!
@@ -200,7 +219,8 @@ module Workspaces
 
     def usage
       'Usage: bin/workspaces serve [--require FILE] | create (--branch REF | --pr NUMBER | --new-branch NAME [--from REF]) [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
-        'list [--pr NUMBER] [--json] | show/start/prepare/restart ID [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | stop ID | ' \
+        'list [--pr NUMBER] [--json] | show/start/prepare/restart ID [--preset NAME] [--set NAME=VALUE] [--unset NAME] [--json] | ' \
+        'resume ID [--from STEP | --only STEP] [--json] | stop ID | ' \
         'exec ID -- COMMAND... | remove ID [--force]'
     end
 

data/lib/workspaces/coordinator.rb

@@ -7,6 +7,7 @@ require_relative 'presentation'
 require_relative 'environment_overrides'
 require_relative 'duration_format'
 require_relative 'build_history'
+require_relative 'resume_plan'
 
 module Workspaces
   class Coordinator
@@ -28,6 +29,25 @@ module Workspaces
       launch(id, restart: true, force: true, prelaunch: settings_update(id, preset, set, unset))
     end
 
+    # Re-runs part of the last run instead of all of it. `mode` is :retry (continue from the first
+    # step that did not finish), :from (that step and everything after it) or :only (exactly that
+    # step). Finished steps keep their time and log; see ResumePlan for what each mode allows.
+    # Returns false when the workspace is busy and raises ArgumentError (with a plain-language
+    # message) when the request cannot be honoured.
+    def rerun(id, mode: :retry, key: nil)
+      workspace = @registry.find(id)
+      lock = acquire_lock(id)
+      return false unless lock
+
+      plan = rerun_plan(id, mode, key)
+      publish_rerun(id, plan)
+      spawn_worker(workspace, false, lock, plan: plan)
+      true
+    rescue StandardError
+      lock&.close unless lock&.closed?
+      raise
+    end
+
     def update_environment(id, set:, remove:)
       restart = Backend.new(id).running?
       launch(id, restart: restart, force: true,
@@ -101,6 +121,7 @@ module Workspaces
         'completed_at' => entry['completed_at'], 'last_error' => entry['last_error'],
         'operation' => entry['operation'], 'failed_phase' => failure_phase(entry, status),
         'steps' => entry.fetch('steps', []), 'total_seconds' => entry['total_seconds'],
+        'resume' => resume_info(id, entry),
         'estimates' => entry.fetch('estimates', {}),
         'step_logs' => include_log && log == 'setup' ? step_logs(id, entry.fetch('steps', [])) : {},
         'backend_log_available' => backend_log_available?(id),
@@ -140,6 +161,28 @@ module Workspaces
       true
     end
 
+    def resume_info(id, entry)
+      steps = entry['steps']
+      return nil if steps.nil? || steps.empty?
+
+      ResumePlan.describe(recipe_steps: Recipe.new.steps, persisted: steps, server_live: Backend.new(id).resumable?)
+    rescue Recipe::Invalid
+      nil
+    end
+
+    def rerun_plan(id, mode, key)
+      entry = @state.get(id) || {}
+      ResumePlan.build(recipe_steps: Recipe.new.steps, persisted: entry['steps'], mode: mode.to_sym, key: key,
+                       server_live: Backend.new(id).resumable?)
+    end
+
+    def publish_rerun(id, plan)
+      update(id, 'status' => 'preparing', 'message' => "Re-running #{plan.description}",
+                 'steps' => plan.steps, 'estimates' => BuildHistory.estimates(plan.steps.map { |step| step['key'] }),
+                 'operation' => 'resume', 'rerun_keys' => plan.run_keys, 'failed_phase' => nil,
+                 'prepare_started_at' => now, 'completed_at' => nil, 'last_error' => nil, 'total_seconds' => nil)
+    end
+
     def acquire_lock(id)
       Config.locks_dir.mkpath
       # The worker owns this duplicate; closing the request's descriptor must not release its lock.
@@ -157,16 +200,16 @@ module Workspaces
       # is read once per run rather than once per poll.
       update(id, 'status' => 'preparing', 'message' => restart ? 'Restarting application' : 'Preparing workspace',
                  'steps' => steps, 'estimates' => BuildHistory.estimates(steps.map { |step| step['key'] }),
-                 'operation' => restart ? 'restart' : 'prepare', 'failed_phase' => nil,
+                 'operation' => restart ? 'restart' : 'prepare', 'rerun_keys' => nil, 'failed_phase' => nil,
                  'prepare_started_at' => now, 'completed_at' => nil, 'last_error' => nil,
                  'total_seconds' => nil)
     end
 
-    def spawn_worker(workspace, restart, lock)
+    def spawn_worker(workspace, restart, lock, plan: nil)
       id = workspace.id
       workers_mutex.synchronize do
         workers[id] = Thread.new do
-          run(workspace, restart: restart)
+          run(workspace, restart: restart, plan: plan)
         ensure
           lock.close
           workers_mutex.synchronize { workers.delete(id) }
@@ -174,14 +217,15 @@ module Workspaces
       end
     end
 
-    def run(workspace, restart:)
+    def run(workspace, restart:, plan: nil)
       id = workspace.id
       started = monotonic
       File.open(Config.setup_log_path(id), 'a') do |file|
         file.sync = true
         log = TeeLog.new(id, file)
-        log.puts "==> #{restart ? 'restarting' : 'preparing'} workspace #{id}; branch and working files unchanged"
-        prepare_and_boot(workspace, log, restart, started)
+        verb = plan ? "re-running #{plan.description} of" : (restart ? 'restarting' : 'preparing')
+        log.puts "==> #{verb} workspace #{id}; branch and working files unchanged"
+        prepare_and_boot(workspace, log, restart, started, plan)
       end
     rescue StandardError => e
       publish_error(id, e, started)
@@ -189,12 +233,17 @@ module Workspaces
 
     # The wall-clock time of the whole run, boot and readiness included. Step durations add up to
     # less than this because orchestration between steps is not inside any step.
-    def prepare_and_boot(workspace, log, restart, started)
+    def prepare_and_boot(workspace, log, restart, started, plan = nil)
       id = workspace.id
-      port = Workflow.new(workspace, log, state: @state).run!(restart: restart)
+      workflow = Workflow.new(workspace, log, state: @state)
+      # Full runs call the workflow exactly as they always have; only a partial re-run passes a plan.
+      port = plan ? workflow.run!(restart: restart, plan: plan) : workflow.run!(restart: restart)
       total = elapsed_since(started)
-      update(id, 'status' => 'ready', 'message' => 'Workspace ready', 'completed_at' => now, 'port' => port,
-                 'total_seconds' => total)
+      # A re-run that left no server running (a step before it on a stopped workspace) keeps the
+      # recorded port as it was; the workspace then reads as stopped until it is started.
+      attributes = { 'status' => 'ready', 'message' => 'Workspace ready', 'completed_at' => now, 'total_seconds' => total }
+      attributes['port'] = port if port
+      update(id, attributes)
       record_run(id, 'complete', total)
     end
 
@@ -212,8 +261,10 @@ module Workspaces
     # Appends to the build history. A problem here must never change how the run itself ended.
     def record_run(id, result, total_seconds)
       entry = @state.get(id) || {}
+      steps = entry['steps']
+      steps = steps.select { |step| entry['rerun_keys'].include?(step['key']) } if entry['rerun_keys'] && steps
       BuildHistory.record(workspace_id: id, operation: entry['operation'], result: result,
-                          total_seconds: total_seconds, steps: entry['steps'])
+                          total_seconds: total_seconds, steps: steps)
     rescue StandardError
       nil
     end

data/lib/workspaces/dashboard/app.js

@@ -7,14 +7,14 @@
   const selectedLog = new URLSearchParams(window.location.search).get('log') === 'backend'
     ? 'backend'
     : 'setup';
-  const allowedActions = ['start', 'prepare', 'restart', 'stop', 'update-pr'];
+  const allowedActions = ['start', 'prepare', 'restart', 'resume', 'stop', 'update-pr'];
   let busy = root.dataset.busy === 'true';
   let started = Date.parse(root.dataset.started);
   let completed = Date.parse(root.dataset.completed);
   let actionsSignature = null;
   function toggleBusyState(nextBusy) {
     busy = !!nextBusy;
-    root.querySelectorAll('.workspace-actions button, .lead__action button').forEach((button) => {
+    root.querySelectorAll('.workspace-actions button, .lead__action button, .step-log__actions button').forEach((button) => {
       button.disabled = busy;
     });
     if (window.WorkspaceEnvironment)
@@ -68,9 +68,12 @@
     const outcome = document.createElement('span');
     outcome.className = 'step-log__outcome step-outcome';
     summary.append(status, name, outcome);
+    const controls = document.createElement('div');
+    controls.className = 'step-log__actions';
+    controls.hidden = true;
     const output = document.createElement('pre');
     output.tabIndex = 0;
-    details.append(summary, output);
+    details.append(summary, controls, output);
     details.addEventListener('toggle', () => {
       if (details.dataset.programmatic === 'true') return;
       userToggled.add(step.key);
@@ -98,6 +101,7 @@
       const parts = summary.children;
       parts[1].textContent = step.label;
       parts[2].textContent = stepOutcome(step);
+      renderStepControls(details, step, view.resume);
       const output = details.querySelector('pre');
       output.setAttribute('aria-label', step.label + ' output');
       const entry = stepLogs && stepLogs[step.key];
@@ -106,6 +110,32 @@
     });
   }
 
+  // Re-run controls for one step. The server says which of them would be accepted right now (a
+  // single step is only offered while the rest of the run is finished, and steps after the server
+  // only while it is up), so the page never offers something that would be refused.
+  function renderStepControls(details, step, resume) {
+    const holder = details.querySelector('.step-log__actions');
+    const modes = (resume && resume.step_modes && resume.step_modes[step.key]) || [];
+    const labels = { only: 'Re-run this step', from: 'Re-run from here' };
+    const signature = modes.join(',');
+    if (holder.dataset.signature === signature) return;
+    holder.dataset.signature = signature;
+    holder.replaceChildren();
+    holder.hidden = modes.length === 0;
+    modes.forEach((mode) => {
+      if (!labels[mode]) return;
+      const form = document.createElement('form');
+      form.method = 'post';
+      form.action = base + '/resume?' + mode + '=' + encodeURIComponent(step.key);
+      const button = document.createElement('button');
+      button.className = 'button button--subtle button--small';
+      button.textContent = labels[mode];
+      form.append(button);
+      holder.append(form);
+    });
+    toggleBusyState(busy);
+  }
+
   // The Full setup log row reads "in progress" while running, then how the run ended and how
   // long it took. Without a recorded total it keeps its plain label.
   function renderFullLogOutcome(view) {

data/lib/workspaces/dashboard/styles.css

@@ -472,6 +472,12 @@ fieldset:disabled {
   border-color: var(--border);
 }
 
+.button--small { padding: 4px 10px; font-size: 12px; }
+
+.step-log__actions { display: flex; flex-wrap: wrap; gap: var(--space-2); padding: var(--space-2) var(--space-3) 0; }
+.step-log__actions[hidden] { display: none; }
+.step-log__actions form { margin: 0; }
+
 .button--danger {
   background: var(--danger);
   color: var(--bg);

data/lib/workspaces/dashboard_view.rb

@@ -226,6 +226,25 @@ module Workspaces
 
     # One GitHub-Actions-style accordion per recipe step. A step that is running or has
     # failed starts open; a completed or not-yet-started one starts closed.
+    # Small forms for re-running just this step or this step and everything after it, shown only
+    # for what the workspace can actually do right now (the server decides, not the page).
+    def step_controls(step)
+      modes = @presentation.dig('resume', 'step_modes')&.fetch(step['key'], nil)
+      return '' if modes.nil? || modes.empty?
+
+      last = @presentation['steps'].last
+      key = ERB::Util.url_encode(step['key'].to_s)
+      forms = []
+      forms << step_control(key, 'only', 'Re-run this step') if modes.include?('only')
+      forms << step_control(key, 'from', 'Re-run from here') if modes.include?('from') && !(modes.include?('only') && last && last['key'] == step['key'])
+      %(<div class="step-log__actions">#{forms.join}</div>)
+    end
+
+    def step_control(key, mode, label)
+      "<form method=\"post\" action=\"/workspaces/#{@id}/resume?#{mode}=#{key}\">" \
+        "<button class=\"button button--subtle button--small\">#{label}</button></form>"
+    end
+
     def step_accordion(step)
       key = escape(step['key'])
       state = escape(step['state'])
@@ -235,6 +254,7 @@ module Workspaces
       <<~HTML
         <details class="step-log" data-step-log="#{key}" data-step-state="#{state}"#{open}#{current}>
           <summary><span class="step-log__status" aria-hidden="true"></span><span class="step-log__name">#{escape(step['label'])}</span><span class="step-log__outcome step-outcome">#{escape(step_outcome(step))}</span></summary>
+          #{step_controls(step)}
           <pre tabindex="0" aria-label="#{escape(step['label'])} output">#{entry ? escape(entry['text']) : ''}</pre>
         </details>
       HTML

data/lib/workspaces/front_door.rb

@@ -10,7 +10,7 @@ require_relative 'proxy_middleware'
 module Workspaces
   class FrontDoor
     WORKSPACE_ROUTE = %r{\A/workspaces/([a-z0-9]+(?:-[a-z0-9]+)*)
-                          (?:/(status|start|prepare|restart|stop|remove|update-pr|environment))?\z}x
+                          (?:/(status|start|prepare|restart|resume|stop|remove|update-pr|environment))?\z}x
 
     # Rack env keys set on requests that reach a ready workspace backend, for use by
     # middleware registered with Workspaces.configure_proxy.
@@ -94,7 +94,7 @@ module Workspaces
       return remove(request, id) if action == 'remove'
       return update_pr(id) if action == 'update-pr'
 
-      perform_action(id, action)
+      perform_action(id, action, request)
       redirect(Config.dashboard_url(id))
     end
 
@@ -109,11 +109,23 @@ module Workspaces
       response(200, body, type: action ? 'application/json' : 'text/html', head: request.head?)
     end
 
-    def perform_action(id, action)
+    # Retries from the first unfinished step by default; `from=<step>` re-runs that step and every
+    # one after it, `only=<step>` re-runs exactly that step.
+    def resume(id, request)
+      from = request&.params&.fetch('from', nil)
+      only = request&.params&.fetch('only', nil)
+      raise ArgumentError, 'Choose either from or only, not both' if from && only
+
+      mode = only ? :only : (from ? :from : :retry)
+      @coordinator.rerun(id, mode: mode, key: only || from)
+    end
+
+    def perform_action(id, action, request = nil)
       case action
       when 'start' then @coordinator.start(id)
       when 'prepare' then @coordinator.start(id, force: true)
       when 'restart' then @coordinator.restart(id)
+      when 'resume' then resume(id, request)
       when 'stop' then stop(id)
       end
     end

data/lib/workspaces/presentation.rb

@@ -6,7 +6,8 @@ module Workspaces
                'preparing' => 'Running setup', 'error' => 'Setup failed',
                'interrupted' => 'Setup interrupted' }.freeze
     ACTIONS = { 'start' => 'Start workspace', 'prepare' => 'Rebuild & restart',
-                'restart' => 'Restart server', 'stop' => 'Stop server' }.freeze
+                'restart' => 'Restart server', 'stop' => 'Stop server',
+                'resume' => 'Retry failed step' }.freeze
 
     # Three layers, from friendly to technical. `lead` is the headline, one sentence and at
     # most one primary action. `environment` (presets and variables) is the area for
@@ -92,7 +93,7 @@ module Workspaces
       { 'title' => title, 'busy' => busy?, 'error' => error, 'steps' => steps,
         'actions' => actions, 'ready' => status == 'ready' && !busy?,
         'state' => state, 'sections' => sections,
-        'headline' => definition[:headline], 'summary' => definition[:summary],
+        'headline' => definition[:headline], 'summary' => summary, 'resume' => resume,
         'lead_action' => lead_action, 'total' => total, 'progress' => progress,
         'current_preset' => current_preset,
         'environment_title' => definition[:environment_title],
@@ -126,15 +127,47 @@ module Workspaces
     end
 
     # The single most useful thing to do next, or nil when the user should just wait.
-    # `open` links straight to the preview; the others are lifecycle form posts.
+    # `open` links straight to the preview; the others are lifecycle form posts. After a failure the
+    # first offer is to carry on from where it stopped; a full re-run stays one click away.
     def lead_action
       case state
       when 'ready' then { 'kind' => 'open', 'label' => 'Open workspace' }
       when 'stopped' then { 'kind' => 'post', 'key' => 'start', 'label' => 'Start workspace' }
-      when 'error', 'interrupted' then retry_action.merge('kind' => 'post')
+      when 'error', 'interrupted' then (retryable? ? resume_action : retry_action).merge('kind' => 'post')
       end
     end
 
+    # What a re-run of part of the last run could do, for the per-step controls and the retry
+    # wording. Nil while a run is in progress, or when the recorded steps cannot be re-run.
+    def resume
+      info = @snapshot['resume']
+      return nil if busy? || !info.is_a?(Hash)
+
+      failed = steps.find { |step| step['state'] == 'failed' }
+      { 'step_modes' => info['step_modes'] || {}, 'retry_from' => info['retry_from'],
+        'retry_label' => info['retry_label'], 'failed_label' => failed && failed['label'] }
+    end
+
+    def retryable?
+      %w(error interrupted).include?(status) && !resume.nil? && !resume['retry_from'].nil?
+    end
+
+    def resume_action
+      action('resume', true).merge('label' => status == 'interrupted' ? 'Continue setup' : 'Retry failed step')
+    end
+
+    # Plain words for what a retry will do, naming the step. A failure at or after the server step
+    # restarts the server (a failed run stops it), so say where the retry really begins.
+    def summary
+      return definition[:summary] unless retryable?
+
+      info = resume
+      failed = info['failed_label'] || info['retry_label']
+      lead = status == 'interrupted' ? "Setup was interrupted during \"#{failed}\"." : "\"#{failed}\" didn't finish."
+      from = info['retry_label'] == failed ? 'it' : "from \"#{info['retry_label']}\""
+      "#{lead} Retrying runs #{from} again and keeps everything that already finished."
+    end
+
     # The preset whose values exactly equal the workspace's saved editable settings, or nil when
     # there are no presets or the settings match none (for example after a hand edit). Presets
     # arrive already completed with the recipe defaults, so equality is a plain comparison.
@@ -196,6 +229,8 @@ module Workspaces
       return [] if busy?
       available = if status == 'ready'
                     %w(prepare restart stop).map { |key| action(key, false) }
+                  elsif retryable?
+                    [resume_action, retry_action.merge('label' => 'Re-run all steps', 'primary' => false)]
                   elsif %w(error interrupted).include?(status)
                     [retry_action]
                   else

data/lib/workspaces/resume_plan.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Workspaces
+  # Decides which steps a re-run covers, from what a workspace last recorded and what the recipe
+  # says now. Pure: no files, no processes, so every rule can be tested directly.
+  #
+  # Three ways to ask:
+  #   :retry  continue from the first step that did not finish, but never later than the server
+  #           step, because a failed run stops the server and everything after it needs a new one
+  #   :from   re-run one step and every step after it
+  #   :only   re-run exactly one step, leaving the rest of the run (and a running server) alone
+  #
+  # Refusals are plain-language ArgumentErrors, so callers can show them as they are.
+  class ResumePlan
+    class Refused < ArgumentError; end
+
+    Plan = Struct.new(:mode, :run_keys, :steps, :touches_server, :after_server, :description, keyword_init: true)
+
+    MODES = %i(only from).freeze
+
+    def self.describe(recipe_steps:, persisted:, server_live: false)
+      new(recipe_steps, persisted).describe(server_live: server_live)
+    end
+
+    def self.build(recipe_steps:, persisted:, mode:, key: nil, server_live: false)
+      new(recipe_steps, persisted).build(mode: mode, key: key, server_live: server_live)
+    end
+
+    def initialize(recipe_steps, persisted)
+      @recipe_keys = recipe_steps.map { |step| step['id'] }
+      @server_key = recipe_steps.find { |step| step['background'] }&.fetch('id')
+      @persisted = Array(persisted).map(&:dup)
+      @keys = @persisted.map { |step| step['key'] }
+    end
+
+    # What the dashboard needs to offer the right buttons, or nil when re-running is not possible
+    # (no recorded steps, or the recipe's steps have changed since they were recorded). Each step
+    # lists the modes that would be accepted for it, by asking `build` rather than repeating its rules.
+    def describe(server_live: false)
+      return nil unless compatible?
+
+      index = retry_index
+      { 'server_key' => @server_key,
+        'retry_from' => index && @keys[index],
+        'retry_label' => index && @persisted[index]['label'],
+        'step_modes' => @keys.to_h { |key| [key, allowed_modes(key, server_live)] } }
+    end
+
+    def build(mode:, key: nil, server_live: false)
+      unless compatible?
+        raise Refused, 'The steps recorded for this workspace no longer match .workspaces.yml; re-run all steps instead'
+      end
+
+      from, to = range_for(mode, key)
+      run_keys = @keys[from..to]
+      touches = (from..to).cover?(server_idx)
+      after = from > server_idx
+      if after && !server_live
+        raise Refused, 'The server is not running, or was started before step re-runs were supported; ' \
+                       're-run from the server step instead'
+      end
+
+      Plan.new(mode: mode, run_keys: run_keys, steps: carried_steps(run_keys), touches_server: touches,
+               after_server: after, description: describe_range(mode, run_keys))
+    end
+
+    private
+
+    # The recorded steps are either the whole recipe or, after a restart, everything from the
+    # server step on. Anything else means the recipe moved on and the record cannot be trusted.
+    def compatible?
+      return false if @server_key.nil? || @keys.empty?
+
+      @keys == @recipe_keys || @keys == @recipe_keys.drop(@recipe_keys.index(@server_key))
+    end
+
+    def server_idx
+      @server_idx ||= @keys.index(@server_key)
+    end
+
+    def retry_index
+      first = @persisted.index { |step| step['state'] != 'complete' }
+      first && [first, server_idx].min
+    end
+
+    def range_for(mode, key)
+      last = @keys.length - 1
+      case mode
+      when :retry
+        index = retry_index
+        raise Refused, 'Every step already completed, so there is nothing to retry' unless index
+
+        [index, last]
+      when :from
+        index = index_of(key)
+        require_finished_before!(index)
+        [index, last]
+      when :only
+        index = index_of(key)
+        if index == server_idx
+          raise Refused, 'Restarting the server means re-running the steps after it; re-run from that step instead'
+        end
+        require_others_finished!(index)
+
+        [index, index]
+      else
+        raise ArgumentError, "Unknown re-run mode: #{mode.inspect}"
+      end
+    end
+
+    # A re-run must never leave an unfinished step behind, so that a successful one always means the
+    # whole workspace is complete.
+    def require_finished_before!(index)
+      first = @persisted.index { |step| step['state'] != 'complete' }
+      return if first.nil? || first >= index
+
+      raise Refused, "\"#{label_at(first)}\" has not finished; re-run from that step or an earlier one"
+    end
+
+    def require_others_finished!(index)
+      other = @persisted.each_index.find { |i| i != index && @persisted[i]['state'] != 'complete' }
+      return if other.nil?
+
+      raise Refused, "\"#{label_at(other)}\" has not finished; re-run from that step instead of a single step"
+    end
+
+    def label_at(index)
+      @persisted[index]['label'] || @keys[index]
+    end
+
+    def allowed_modes(key, server_live)
+      MODES.select do |mode|
+        build(mode: mode, key: key, server_live: server_live)
+        true
+      rescue Refused
+        false
+      end.map(&:to_s)
+    end
+
+    def index_of(key)
+      @keys.index(key.to_s) || raise(Refused, "Unknown step: #{key.to_s[0, 60].inspect}")
+    end
+
+    # The step list to publish: finished work stays as it was, the steps about to run start over.
+    def carried_steps(run_keys)
+      @persisted.map do |step|
+        next step unless run_keys.include?(step['key'])
+
+        step.merge('state' => 'pending', 'duration_seconds' => nil).tap { |reset| reset.delete('started_at') }
+      end
+    end
+
+    def describe_range(mode, run_keys)
+      names = run_keys.map { |key| @persisted[@keys.index(key)]['label'] || key }
+      case mode
+      when :only then "only #{names.first}"
+      when :from then "from #{names.first}"
+      else "from #{names.first}"
+      end
+    end
+  end
+end

data/lib/workspaces/step_log.rb

@@ -41,9 +41,13 @@ module Workspaces
     end
 
     # Clears every step file; called when a run begins so a restart never shows stale steps.
-    def self.reset(workspace_id)
+    def self.reset(workspace_id, keys: nil)
       dir = Config.step_logs_dir(workspace_id, create: false)
-      Dir.glob(dir.join('*.log')).each { |path| File.delete(path) } if dir.directory?
+      return unless dir.directory?
+
+      Dir.glob(dir.join('*.log')).each do |path|
+        File.delete(path) if keys.nil? || keys.include?(File.basename(path, '.log'))
+      end
     end
 
     private

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.14'
+  VERSION = '0.1.15'
 end

data/lib/workspaces/workflow.rb

@@ -16,20 +16,28 @@ module Workspaces
       @backend = Backend.new(workspace.id)
     end
 
-    def run!(restart: false)
+    # `plan` (a ResumePlan::Plan) re-runs part of the recipe: finished steps keep their state, time
+    # and log, only the planned steps start over, and the server is stopped and restarted only when
+    # the planned steps include the one that starts it. Without a plan the whole operation runs.
+    #
+    # Returns the server's port, or nil when no server is running afterwards (which can only happen
+    # when a plan re-ran a step before the server on a workspace whose server was stopped).
+    def run!(restart: false, plan: nil)
       recipe = Recipe.new
       overrides = EnvironmentOverrides.new(@workspace.id).load
-      steps = recipe.for_operation(restart: restart)
-      publish_steps(steps)
-      StepLog.reset(@workspace.id)
-      @backend.stop!
-      context = build_context(@backend.reserve!)
+      steps = plan ? recipe.steps.select { |step| plan.run_keys.include?(step['id']) } : recipe.for_operation(restart: restart)
+      plan ? @state.set(@workspace.id, 'steps' => plan.steps) : publish_steps(steps)
+      StepLog.reset(@workspace.id, keys: plan&.run_keys)
+      context = prepare_server(plan)
       runner = CommandRunner.new(@workspace.path, @log)
       steps.each { |step| execute(step, recipe, context, runner, overrides) }
-      @backend.ensure_alive!
-      @backend.port
+      return finish_full_run if plan.nil? || plan.touches_server || plan.after_server
+
+      @backend.running? ? @backend.port : nil
     rescue StandardError
-      @backend.stop!
+      # A server this run started (or would have replaced) is not trustworthy after a failure. One
+      # this run never touched is left as it was.
+      @backend.stop! if plan.nil? || plan.touches_server
       raise
     ensure
       @log.finish_step
@@ -37,19 +45,38 @@ module Workspaces
 
     private
 
+    # Stops the old server and reserves a fresh port and token when this run will start the server;
+    # otherwise the running server's own port and token are reused, so steps see the same values.
+    def prepare_server(plan)
+      if plan.nil? || plan.touches_server
+        @backend.stop!
+        return build_context(@backend.reserve!)
+      end
+
+      @server_started = plan.after_server
+      build_context(@backend.port, run_id: @backend.run_id)
+    end
+
+    # A run that covers the server step (or follows it) ends with a liveness check, exactly as a
+    # full run always has, and reports the port of the server it leaves running.
+    def finish_full_run
+      @backend.ensure_alive!
+      @backend.port
+    end
+
     def publish_steps(steps)
       @state.set(@workspace.id, 'steps' => steps.map do |step|
         { 'key' => step['id'], 'label' => step['name'], 'state' => 'pending', 'duration_seconds' => nil }
       end)
     end
 
-    def build_context(port)
+    def build_context(port, run_id: nil)
       {
         'WORKSPACE_ID' => @workspace.id, 'WORKSPACE_PATH' => @workspace.path.to_s,
         'WORKSPACE_REPO_ROOT' => Config.repo_root.to_s, 'WORKSPACE_PORT' => port.to_s,
         'WORKSPACE_URL' => Config.preview_url(@workspace.id).delete_suffix('/'),
         'WORKSPACE_HOST' => Config.preview_host(@workspace.id),
-        'WORKSPACE_CACHE_DIR' => Config.home.to_s, 'WORKSPACE_RUN_ID' => SecureRandom.hex(24)
+        'WORKSPACE_CACHE_DIR' => Config.home.to_s, 'WORKSPACE_RUN_ID' => run_id || SecureRandom.hex(24)
       }
     end
 
@@ -62,6 +89,7 @@ module Workspaces
       env = recipe.env(step, context, overrides: overrides)
       if step['background']
         @backend.start!(@workspace, command, env: env)
+        @state.set(@workspace.id, 'run_id' => context.fetch('WORKSPACE_RUN_ID'))
       else
         runner.run!(command, env: env, timeout: step.fetch('timeout'))
         @backend.ensure_alive! if @server_started

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.14
+  version: 0.1.15
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -94,6 +94,7 @@ files:
 - lib/workspaces/proxy_middleware.rb
 - lib/workspaces/recipe.rb
 - lib/workspaces/registry.rb
+- lib/workspaces/resume_plan.rb
 - lib/workspaces/state_store.rb
 - lib/workspaces/step_log.rb
 - lib/workspaces/tee_log.rb