workspaces 0.1.12 → 0.1.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1425a9356962c4990de3a5a0f5ffb1b8660325bcff165bfb8336fb7c468696ef
-  data.tar.gz: 878aff1b14d9ec8f13902a9ac3abd35e47cce3536d640d25b15a8e5a50426936
+  metadata.gz: 160b209187a95a674c6ce4936b4b2863ed5893ac8331f1f0345d550cf09f2f2d
+  data.tar.gz: ba7ef0dd3ed8c913ea29683f641c1d4ac314ee15a1c201dd45634d45a8a980bc
 SHA512:
-  metadata.gz: '059361fdfac7d7328f4f50d31efeb647656375582a4d178f4f0d6f7c62affae21eaf53f67cf9590da272f29803fdefa904ebba36e18c8b570b97b12ad9c86ca3'
-  data.tar.gz: c623574a0d2105f00b22ed460c597941e09fead329a335d47f01c9967d65ec84da098e23c08c4fdb0ace7358c6d7c929f4d5fa6a228bf21fb12a960a75d4b8c8
+  metadata.gz: 978a8f06eda4d6d9c0c443499f1cf28f41c33800b3394b40fb56dd8771e0f1283001a4e24effcb3f7c52563023a18e1f48bfe884f97bd255642ff9379b9ea095
+  data.tar.gz: 8162b0c59925b414a1af0ff511fcc6bee2d79f83bb42d452614ef68f79c7ee52e42cb89531c21c5e77b29bc76b76cdfea4f4b5fff73fff2217b49217a0321a2c

data/DESIGN.md

@@ -67,6 +67,8 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
   - **Capture**: `StepLog` wraps the combined log. Every line still goes to the combined `<id>.setup.log`; while a step is current the same scrubbed text also goes to `logs/<id>.steps/<step-id>.log`. A step's file is truncated when it begins, the files are cleared when a run starts, and a failing step records its error message in its own file.
   - **Read**: the snapshot carries `step_logs` (the tail of each step that has output, with a `truncated` flag) for the setup view only, and `backend_log_available`.
   - **Tabs**: *Setup steps* (the accordions) and *Web server log*. The server tab appears only once the backend log has content. The combined log stays reachable as a final, collapsed *Full setup log* row, which also covers workspaces set up before step files existed.
+- **Build progress**: while a build is being prepared the lead is the headline, a progress bar (`role="progressbar"` with a text value), and one line saying *Step n of m · name*, the percentage, the elapsed time and an estimate. The server computes the numbers from the step states and per-step averages frozen when the run began (`Progress`), and the script only draws them; the elapsed clock ticks locally between polls. A step well past its usual time turns the bar amber and the estimate reads "Taking longer than usual". Without history there is no time estimate. The bar is hidden when no build is running.
+- **Build history**: every finished run is appended to `build-history.jsonl` (`BuildHistory`). Estimates are the mean of a step's last 10 successful completions; failed runs are recorded but never counted. Recording is best-effort and cannot fail a build.
 - **Bounded log panel**: monospace text, fixed max height, manual-scroll-safe updates
 - **Log source switcher**: two native links inside one log panel (Setup steps, Web server log), with current selection announced through `aria-current`; only the selected view is loaded and refreshed. Setup steps is the default.
 - **Preview destination**: a small muted URL in Technical details, visible before readiness; the large Open workspace button is reserved for ready servers.

data/README.md

@@ -39,6 +39,42 @@ The returned JSON includes the workspace ID, dashboard URL, and preview URL. You
 create from a pull request with `create --pr NUMBER`, or create a new branch with
 `create --new-branch NAME --from REF`. Run `help` for lifecycle and other commands.
 
+### Git LFS
+
+If the project keeps large files in [Git LFS](https://git-lfs.com), a new workspace does not
+copy them. Creating a workspace (and fast-forwarding a PR workspace to a newer head) leaves
+those files as small pointer files, and `git status` stays clean. Without this, every
+workspace would hold a full second copy of every LFS file, even though the source
+checkout's LFS store is already shared.
+
+List the paths a workspace actually needs in `.workspaces.yml`:
+
+```yaml
+lfs:
+  fetch:
+    - eval/amc/images/golden/**
+    - spec/fixtures/images/**
+```
+
+That adds a first step, **Fetch Git LFS files**, which runs
+`git lfs pull --include=<paths>` in the workspace. It appears in the step list with its own
+log, time and place in the progress estimate like any other step, and it runs on `start` and
+`prepare` but not on `restart`. Paths are repository-relative patterns; absolute paths,
+`..`, a leading `-`, commas and control characters are rejected when the recipe loads.
+Omit `lfs` and nothing changes except that files stay as pointers.
+
+A few things worth knowing:
+
+- Files are fetched from the objects the source repository already has when it can, and from
+  the remote otherwise. If neither works (no network, or no credentials for LFS) the step
+  fails and the workspace reports it, rather than silently leaving pointers.
+- A file that is still a pointer reads as a ~130 byte text file starting with
+  `version https://git-lfs`. If a test or build reads an LFS file, add its path to
+  `lfs.fetch`.
+- To fetch more by hand in an existing workspace:
+  `workspaces exec <id> -- git lfs pull --include='path/**'`.
+- Workspaces created before this behavior keep their real files; nothing is converted.
+
 ### Step timings
 
 Per-step durations are persisted in seconds in workspace step status JSON, so they
@@ -54,6 +90,30 @@ Interrupted steps have no recorded duration. Step timings are not the total
 workflow wall-clock time; orchestration overhead can fall outside the steps, which is
 why the total is measured separately and is usually a little larger than their sum.
 
+### Build history and the progress bar
+
+While a workspace is being prepared the dashboard shows a progress bar with the current step,
+the percentage, the elapsed time and, once there is history, an estimate of what is left.
+
+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
+version, and each step's id, state and seconds. To see which step is getting slower:
+
+```sh
+jq -r 'select(.result=="complete") | .at[:10] as $d | .steps[] | [$d, .id, .seconds] | @tsv' \
+  "$WORKSPACES_HOME/build-history.jsonl"
+```
+
+Estimates are the mean of each step over its last 10 successful runs. Failed runs are
+recorded for the trend but never count toward "usual". They are read once when a run starts,
+so the bar does not shift while you watch it. Percentages weigh each step by how long it
+usually takes, count the running step by how much of its usual time has passed, never reach
+100% until the run finishes, and hold a step that overruns below done. A step more than 1.5
+times its usual time is flagged as taking longer than usual. With no history yet, steps weigh
+the same and no time estimate is shown. Delete the file to start the estimates over.
+
 ## Serve the dashboard and previews
 
 Run `serve` in a separate terminal using the **same project root and `WORKSPACES_HOME`**

data/lib/workspaces/build_history.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'fileutils'
+require_relative 'version'
+
+module Workspaces
+  # A quiet, append-only record of every finished run, plus the per-step averages derived from it.
+  #
+  # One JSON object per line in `build-history.jsonl` under the Workspaces home, shared by every
+  # workspace of the project, so it can be read with jq or loaded into a spreadsheet to see how
+  # setup times trend. Only successful runs feed the progress estimates; failed runs are recorded
+  # for the trend but never skew what "usual" means.
+  #
+  # Nothing here may break a build: recording failures are swallowed with a one-line warning.
+  module BuildHistory
+    SAMPLE_SIZE = 10
+    # The estimates only need recent runs, so a long history is read from its tail.
+    READ_BYTES = 512 * 1024
+
+    module_function
+
+    def record(workspace_id:, operation:, result:, total_seconds:, steps:, now: Time.now.utc)
+      line = JSON.generate(
+        'at' => now.iso8601, 'workspace_id' => workspace_id, 'operation' => operation, 'result' => result,
+        'total_seconds' => total_seconds, 'workspaces_version' => VERSION,
+        'steps' => Array(steps).map { |step| { 'id' => step['key'], 'state' => step['state'], 'seconds' => step['duration_seconds'] } }
+      )
+      path = Config.build_history_path
+      FileUtils.mkdir_p(path.dirname)
+      File.open(path, 'a') do |file|
+        file.flock(File::LOCK_EX)
+        file.puts(line)
+      end
+      true
+    rescue StandardError => e
+      warn "[Workspaces] build history not recorded: #{e.class}"
+      false
+    end
+
+    # Mean seconds for each requested step id, over its last SAMPLE_SIZE completions in
+    # successful runs. Steps never seen succeed are omitted.
+    def estimates(step_ids)
+      wanted = step_ids.to_a
+      samples = Hash.new { |hash, key| hash[key] = [] }
+      records.reverse_each do |record|
+        next unless record['result'] == 'complete'
+
+        Array(record['steps']).each do |step|
+          id = step['id']
+          seconds = step['seconds']
+          next unless wanted.include?(id) && step['state'] == 'complete' && seconds.is_a?(Numeric) && seconds >= 0
+          next if samples[id].length >= SAMPLE_SIZE
+
+          samples[id] << seconds
+        end
+      end
+      samples.transform_values { |values| (values.sum / values.length).round(3) }
+    rescue StandardError
+      {}
+    end
+
+    # Newest last. Unreadable or half-written lines are skipped.
+    def records
+      path = Config.build_history_path
+      return [] unless path.file?
+
+      text = File.open(path, 'rb') do |file|
+        size = file.size
+        file.seek(-READ_BYTES, IO::SEEK_END) if size > READ_BYTES
+        data = file.read.force_encoding('UTF-8')
+        size > READ_BYTES ? data.sub(/\A[^\n]*\n/, '') : data
+      end
+      text.each_line.filter_map do |line|
+        parsed = JSON.parse(line)
+        parsed if parsed.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/workspaces/coordinator.rb

@@ -6,6 +6,7 @@ require_relative 'tee_log'
 require_relative 'presentation'
 require_relative 'environment_overrides'
 require_relative 'duration_format'
+require_relative 'build_history'
 
 module Workspaces
   class Coordinator
@@ -100,6 +101,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'],
+        'estimates' => entry.fetch('estimates', {}),
         'step_logs' => include_log && log == 'setup' ? step_logs(id, entry.fetch('steps', [])) : {},
         'backend_log_available' => backend_log_available?(id),
         'log_tail' => include_log ? log_tail(id, log) : '', 'log_source' => log, 'port' => entry['port'],
@@ -151,8 +153,10 @@ module Workspaces
       steps = recipe.for_operation(restart: restart).map do |step|
         { 'key' => step['id'], 'label' => step['name'], 'state' => 'pending', 'duration_seconds' => nil }
       end
+      # Frozen for the whole run, so the bar does not shift under the reader and the history file
+      # is read once per run rather than once per poll.
       update(id, 'status' => 'preparing', 'message' => restart ? 'Restarting application' : 'Preparing workspace',
-                 'steps' => steps,
+                 'steps' => steps, 'estimates' => BuildHistory.estimates(steps.map { |step| step['key'] }),
                  'operation' => restart ? 'restart' : 'prepare', 'failed_phase' => nil,
                  'prepare_started_at' => now, 'completed_at' => nil, 'last_error' => nil,
                  'total_seconds' => nil)
@@ -188,17 +192,30 @@ module Workspaces
     def prepare_and_boot(workspace, log, restart, started)
       id = workspace.id
       port = Workflow.new(workspace, log, state: @state).run!(restart: restart)
+      total = elapsed_since(started)
       update(id, 'status' => 'ready', 'message' => 'Workspace ready', 'completed_at' => now, 'port' => port,
-                 'total_seconds' => elapsed_since(started))
+                 'total_seconds' => total)
+      record_run(id, 'complete', total)
     end
 
     def publish_error(id, exception, started = nil)
       detail = scrub("#{exception.class}: #{exception.message}", id: id)
       $stdout.puts "[Workspace #{id}] ERROR: #{detail}"
       File.open(Config.setup_log_path(id), 'a') { |file| file.puts "ERROR: #{detail}" }
+      total = started && elapsed_since(started)
       update(id, 'status' => 'error', 'message' => 'Workspace preparation failed', 'last_error' => detail,
                  'failed_phase' => @state.get(id)&.fetch('status', nil), 'completed_at' => now,
-                 'total_seconds' => started && elapsed_since(started))
+                 'total_seconds' => total)
+      record_run(id, 'failed', total)
+    end
+
+    # 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) || {}
+      BuildHistory.record(workspace_id: id, operation: entry['operation'], result: result,
+                          total_seconds: total_seconds, steps: entry['steps'])
+    rescue StandardError
+      nil
     end
 
     def monotonic

data/lib/workspaces/dashboard/app.js

@@ -206,16 +206,7 @@
   function renderLead(view) {
     node('status').textContent = view.headline || view.title;
     node('summary').textContent = view.summary || '';
-    const subtitle = node('subtitle');
-    const activity = node('activity');
-    if (subtitle) {
-      const text = view.subtitle || '';
-      subtitle.hidden = !text;
-      // The text has its own element, so it can be set whether or not the server rendered any.
-      const target = node('subtitle-text');
-      if (target) target.textContent = text;
-    }
-    if (activity) activity.hidden = !view.busy;
+    renderProgress(view.progress);
     const title = node('environment-title');
     if (title && view.environment_title) title.textContent = view.environment_title;
     const badge = node('environment-preset-badge');
@@ -229,6 +220,29 @@
   // The lead action is a lifecycle post (start/retry) or, when ready, the preview link
   // rendered separately as #preview. Rebuild only when it actually changes.
   let leadSignature = null;
+  // The server decides the percentage, the step line and the estimate; this only draws them. The
+  // elapsed clock is ticked locally each second (see tick) so it keeps moving between polls.
+  function renderProgress(progress) {
+    const holder = node('build-progress');
+    if (!holder) return;
+    holder.hidden = !progress;
+    if (!progress) return;
+    const percent = progress.percent;
+    const bar = node('progress-bar');
+    bar.setAttribute('aria-valuenow', String(percent));
+    bar.setAttribute(
+      'aria-valuetext',
+      [progress.step_text + ' · ' + progress.step_label, progress.eta_text].filter(Boolean).join('. ')
+    );
+    bar.dataset.slow = progress.slow ? 'true' : 'false';
+    node('progress-fill').style.inlineSize = percent + '%';
+    node('progress-step').textContent = progress.step_text + ' · ' + progress.step_label;
+    node('progress-percent').textContent = percent + '%';
+    node('progress-eta').textContent = progress.eta_text ? ' · ' + progress.eta_text : '';
+    if (!Number.isFinite(started) && Number.isFinite(progress.elapsed_seconds))
+      node('elapsed').textContent = formatDuration(progress.elapsed_seconds);
+  }
+
   function renderLeadAction(action) {
     const holder = node('lead-action');
     if (!holder) return;

data/lib/workspaces/dashboard/styles.css

@@ -155,6 +155,17 @@ h1 {
 .lead h2 { font-size: clamp(1.4rem, 2vw + 1rem, 1.9rem); line-height: 1.2; }
 .lead__summary { max-inline-size: 38rem; color: var(--muted); font-size: 1.05rem; line-height: 1.5; }
 .lead__actions { display: flex; flex-wrap: wrap; gap: var(--space-3); }
+.lead__actions:empty { display: none; }
+
+/* The build progress bar: a plain track and fill, then one line saying which step and how long. */
+.build-progress { display: grid; gap: var(--space-3); }
+.progress-bar { block-size: 10px; border-radius: 999px; background: color-mix(in oklab, var(--muted) 22%, transparent); overflow: hidden; }
+.progress-bar__fill { display: block; block-size: 100%; border-radius: inherit; background: var(--accent); transition: inline-size 600ms ease; }
+.progress-bar[data-slow='true'] .progress-bar__fill { background: var(--warning); }
+.progress-meta { display: flex; flex-wrap: wrap; justify-content: space-between; align-items: baseline; gap: var(--space-1) var(--space-4); }
+.progress-meta__step { display: flex; align-items: center; gap: var(--space-2); font-weight: 600; min-inline-size: 0; overflow-wrap: anywhere; }
+.progress-meta__time { font-variant-numeric: tabular-nums; }
+@media (prefers-reduced-motion: reduce) { .progress-bar__fill { transition: none; } }
 .lead__action:empty { display: none; }
 .button--large { min-block-size: 52px; padding-inline: var(--space-8); font-size: 16px; border-radius: var(--radius); }
 

data/lib/workspaces/dashboard/template.html.erb

@@ -7,7 +7,13 @@
     <div class="lead__text">
       <h2 id="status" role="status"><%= escape(@presentation['headline']) %></h2>
       <p id="summary" class="lead__summary"><%= escape(@presentation['summary']) %></p>
-      <p id="subtitle" class="muted" <%= 'hidden' unless @presentation['subtitle'] %>><span id="subtitle-text"><%= escape(@presentation['subtitle']) %></span><span id="activity" <%= 'hidden' unless @presentation['busy'] %>> · <span class="activity-dot" aria-hidden="true"></span> <span id="elapsed">—</span></span></p>
+    </div>
+    <div class="build-progress" id="build-progress" <%= 'hidden' unless @presentation['progress'] %>>
+      <div class="progress-bar" id="progress-bar" role="progressbar" aria-label="Setup progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="<%= progress_percent %>" aria-valuetext="<%= escape(progress_valuetext) %>" data-slow="<%= @presentation.dig('progress', 'slow') ? 'true' : 'false' %>"><span class="progress-bar__fill" id="progress-fill" style="inline-size: <%= progress_percent %>%"></span></div>
+      <div class="progress-meta">
+        <p class="progress-meta__step"><span class="activity-dot" aria-hidden="true"></span><span id="progress-step"><%= escape(progress_step_text) %></span></p>
+        <p class="progress-meta__time muted"><span id="progress-percent"><%= progress_percent %>%</span><span aria-hidden="true"> · </span><span id="elapsed"><%= escape(progress_elapsed_text) %></span><span id="progress-eta"><%= escape(progress_eta_suffix) %></span></p>
+      </div>
     </div>
     <div class="lead__actions">
       <a id="preview" class="button button--primary button--large" href="<%= escape(Config.preview_url(@id)) %>" <%= 'hidden' unless @presentation['ready'] %> target="_blank" rel="noopener noreferrer">Open workspace</a>

data/lib/workspaces/dashboard_view.rb

@@ -186,6 +186,35 @@ module Workspaces
       text ? "#{total['state']} · #{text}" : 'everything, in order'
     end
 
+    # The bar's text, rendered on the server for the first paint; app.js keeps it current after that.
+    def progress
+      @presentation['progress'] || {}
+    end
+
+    def progress_percent
+      progress.fetch('percent', 0)
+    end
+
+    def progress_step_text
+      return '' if progress.empty?
+
+      "#{progress['step_text']} · #{progress['step_label']}"
+    end
+
+    def progress_elapsed_text
+      DurationFormat.call(progress['elapsed_seconds']) || '—'
+    end
+
+    def progress_eta_suffix
+      progress['eta_text'] ? " · #{progress['eta_text']}" : ''
+    end
+
+    def progress_valuetext
+      return '' if progress.empty?
+
+      [progress_step_text, progress['eta_text']].compact.join('. ')
+    end
+
     def preset_badge_text
       name = @presentation['current_preset']
       name ? "Preset: #{name}" : ''

data/lib/workspaces/paths.rb

@@ -27,6 +27,11 @@ module Workspaces
       home.join('state.json')
     end
 
+    # Every finished run, one JSON object per line, shared by all workspaces of this project.
+    def build_history_path
+      home.join('build-history.jsonl')
+    end
+
     def log_path(workspace_id, create: true)
       setup_log_path(workspace_id, create: create)
     end

data/lib/workspaces/presentation.rb

@@ -1,3 +1,5 @@
+require_relative 'progress'
+
 module Workspaces
   class Presentation
     TITLES = { 'idle' => 'Ready to start', 'stopped' => 'Server stopped', 'ready' => 'Workspace ready',
@@ -41,7 +43,7 @@ module Workspaces
       'busy' => {
         sections: %w(lead technical log),
         headline: 'Setting things up…',
-        summary: "This usually takes a few minutes. We'll take you to the preview when it's ready.",
+        summary: "We'll take you to the preview as soon as it's ready.",
         environment_submit: 'Save & restart', environment_title: 'Change settings',
         open_environment: false, open_technical: true
       },
@@ -91,7 +93,7 @@ module Workspaces
         'actions' => actions, 'ready' => status == 'ready' && !busy?,
         'state' => state, 'sections' => sections,
         'headline' => definition[:headline], 'summary' => definition[:summary],
-        'subtitle' => subtitle, 'lead_action' => lead_action, 'total' => total,
+        'lead_action' => lead_action, 'total' => total, 'progress' => progress,
         'current_preset' => current_preset,
         'environment_title' => definition[:environment_title],
         'environment_submit' => definition[:environment_submit],
@@ -159,11 +161,12 @@ module Workspaces
       { 'state' => failed ? 'failed' : 'complete', 'seconds' => seconds }
     end
 
-    # What is happening right now, in the quiet line under the headline.
-    def subtitle
-      return nil unless state == 'busy'
+    # The progress bar's numbers, only while a build is being prepared (not for a lone command
+    # on a ready workspace, which has no steps of its own to measure).
+    def progress
+      return nil unless status == 'preparing' && !steps.empty?
 
-      @snapshot['message']
+      Progress.new(steps: steps, estimates: @snapshot['estimates'], started_at: @snapshot['prepare_started_at']).to_h
     end
 
     def title

data/lib/workspaces/progress.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative 'duration_format'
+
+module Workspaces
+  # A deliberately simple read on how far along a run is, for a progress bar.
+  #
+  # With history: each step carries weight equal to its usual duration, finished steps count in
+  # full, and the running step counts by how much of its usual time has passed. Without history
+  # every step weighs the same and only finished steps count. The bar never claims 100% while
+  # work remains, and a step that overruns its usual time is held back so the bar waits for it.
+  class Progress
+    MIN_WEIGHT = 1.0
+    MAX_PERCENT = 99
+    STEP_CAP = 0.95
+    SLOW_FACTOR = 1.5
+
+    def initialize(steps:, estimates:, started_at:, now: Time.now)
+      @steps = steps
+      @estimates = estimates || {}
+      @started_at = parse(started_at)
+      @now = now
+    end
+
+    def to_h
+      return nil if @steps.empty?
+
+      { 'percent' => percent, 'step_label' => current_step['label'], 'step_text' => "Step #{current_index + 1} of #{@steps.length}",
+        'elapsed_seconds' => elapsed, 'eta_text' => eta_text, 'slow' => slow?, 'estimated' => estimated? }
+    end
+
+    private
+
+    def percent
+      done = 0.0
+      @steps.each_with_index do |step, index|
+        case step['state']
+        when 'complete' then done += weights[index]
+        when 'active' then done += weights[index] * active_fraction(step, weights[index])
+        end
+      end
+      [(done / weights.sum * 100).floor, MAX_PERCENT].min
+    end
+
+    def active_fraction(step, weight)
+      return 0.0 unless estimated?
+
+      [step_elapsed(step) / weight, STEP_CAP].min
+    end
+
+    def estimated?
+      @steps.any? { |step| estimate(step) }
+    end
+
+    def estimate(step)
+      value = @estimates[step['key']]
+      value.is_a?(Numeric) && value.positive? ? [value, MIN_WEIGHT].max : nil
+    end
+
+    # A step with no history of its own borrows the average of the ones that have it.
+    def weights
+      @weights ||= begin
+        known = @steps.filter_map { |step| estimate(step) }
+        fallback = known.empty? ? 1.0 : known.sum / known.length
+        @steps.map { |step| estimate(step) || fallback }
+      end
+    end
+
+    def current_index
+      @current_index ||= @steps.index { |step| step['state'] == 'active' } ||
+                         @steps.index { |step| step['state'] == 'pending' } || (@steps.length - 1)
+    end
+
+    def current_step
+      @steps[current_index]
+    end
+
+    def step_elapsed(step)
+      started = parse(step['started_at'])
+      started ? [@now - started, 0].max : 0.0
+    end
+
+    def slow?
+      step = @steps.find { |item| item['state'] == 'active' }
+      estimated? && !step.nil? && step_elapsed(step) > weights[@steps.index(step)] * SLOW_FACTOR
+    end
+
+    def remaining
+      @steps.each_with_index.sum do |step, index|
+        case step['state']
+        when 'pending' then weights[index]
+        when 'active' then [weights[index] - step_elapsed(step), 0].max
+        else 0
+        end
+      end
+    end
+
+    def eta_text
+      return nil unless estimated?
+      return 'Taking longer than usual' if slow?
+      return 'Almost done' if remaining < 5
+
+      "About #{DurationFormat.call(round_eta(remaining))} left"
+    end
+
+    # A countdown that changes by single seconds reads as noise; round to what a person would say.
+    def round_eta(seconds)
+      seconds >= 60 ? (seconds / 10.0).round * 10 : (seconds / 5.0).round * 5
+    end
+
+    def elapsed
+      @started_at ? [(@now - @started_at).floor, 0].max : nil
+    end
+
+    def parse(value)
+      value && Time.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/workspaces/recipe.rb

@@ -7,7 +7,9 @@ module Workspaces
     class Invalid < ArgumentError; end
     RESERVED_ENV = %w(WORKSPACE_ID WORKSPACE_PATH WORKSPACE_REPO_ROOT WORKSPACE_PORT WORKSPACE_URL
                       WORKSPACE_HOST WORKSPACE_CACHE_DIR WORKSPACE_RUN_ID).freeze
-    attr_reader :steps, :environment, :default_editable_env, :environment_presets
+    LFS_STEP_ID = 'lfs'.freeze
+    LFS_STEP_NAME = 'Fetch Git LFS files'.freeze
+    attr_reader :steps, :environment, :default_editable_env, :environment_presets, :lfs_fetch
 
     def initialize(root: Config.repo_root)
       @root = root
@@ -16,7 +18,9 @@ module Workspaces
       @default_editable_env = validate_editable_env!(document.fetch('default_editable_env', {}))
       @environment_presets = validate_environment_presets!(document.fetch('environment_presets', {}))
       @environment = validate_env!(document.fetch('env', {}))
+      @lfs_fetch = validate_lfs!(document.fetch('lfs', {}))
       @steps = document.fetch('steps').map { |step| validate_step!(step) }
+      @steps = [lfs_step] + @steps unless lfs_fetch.empty?
       validate_editable_overlap!
       validate_sequence!
     rescue Errno::ENOENT
@@ -29,6 +33,13 @@ module Workspaces
       restart ? steps.drop(steps.index { |step| step['background'] }) : steps
     end
 
+    # Files fetched into the workspace come from the LFS objects the source repository already
+    # has, then are linked in by `git lfs pull`; the source's store is shared by every workspace.
+    def lfs_step
+      { 'id' => LFS_STEP_ID, 'name' => LFS_STEP_NAME, 'timeout' => 600, 'env' => {}, 'background' => false,
+        'run' => ['git', 'lfs', 'pull', "--include=#{lfs_fetch.join(',')}"] }
+    end
+
     def command(step, context)
       command = step.fetch('run')
       return ['sh', '-c', command] if command.is_a?(String)
@@ -50,7 +61,7 @@ module Workspaces
         raise Invalid,
               'Configuration must be a mapping with version: 1'
       end
-      unknown_keys!(document, %w(version env default_editable_env environment_presets steps))
+      unknown_keys!(document, %w(version env default_editable_env environment_presets lfs steps))
       raise Invalid, 'steps must be a nonempty array' unless document['steps'].is_a?(Array) && !document['steps'].empty?
     end
 
@@ -100,6 +111,26 @@ module Workspaces
             'timeout applies to foreground steps, not the server lifetime'
     end
 
+    # `lfs: { fetch: [path, ...] }` names the Git LFS files a workspace needs. Everything else
+    # stays a pointer. Paths are repository-relative globs handed to `git lfs pull --include`, so
+    # they are checked for the things that would make that unsafe or surprising.
+    def validate_lfs!(value)
+      raise Invalid, 'lfs must be a mapping' unless value.is_a?(Hash)
+
+      unknown_keys!(value, %w(fetch))
+      paths = value.fetch('fetch', [])
+      raise Invalid, 'lfs.fetch must be an array of paths' unless paths.is_a?(Array)
+
+      paths.each do |path|
+        unless path.is_a?(String) && !path.strip.empty? && path == path.strip
+          raise Invalid, 'lfs.fetch paths must be nonempty trimmed strings'
+        end
+        raise Invalid, 'lfs.fetch paths cannot contain commas or control characters' if path.match?(/[,[:cntrl:]]/)
+        raise Invalid, 'lfs.fetch paths must be relative to the repository' if path.start_with?('/', '-') || path.split('/').include?('..')
+      end
+      paths.uniq
+    end
+
     def validate_env!(values)
       raise Invalid, 'env must be a mapping' unless values.is_a?(Hash)
       values.each do |key, value|

data/lib/workspaces/version.rb

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

data/lib/workspaces/workflow.rb

@@ -86,8 +86,9 @@ module Workspaces
     def progress(step, status, duration_seconds: nil)
       @state.transaction do |data|
         entry = data.fetch(@workspace.id)
-        entry['steps'].find { |item| item['key'] == step['id'] }
-          .merge!('state' => status, 'duration_seconds' => duration_seconds)
+        record = entry['steps'].find { |item| item['key'] == step['id'] }
+        record.merge!('state' => status, 'duration_seconds' => duration_seconds)
+        record['started_at'] = Time.now.utc.iso8601(3) if status == 'active'
         entry['message'] = step['name']
         entry['current_step'] = step['id']
         entry['updated_at'] = Time.now.utc.iso8601

data/lib/workspaces/worktree.rb

@@ -12,6 +12,12 @@ module Workspaces
     class UpdateError < StandardError; end
     AUTH_FAILURE = Regexp.union(/could not read (?:Username|Password)|terminal prompts disabled|Authentication failed/i,
                                 /Permission denied \(publickey\)|gh auth login|HTTP 401|HTTP 403/i)
+    # A project that keeps large files in Git LFS would otherwise copy every one of them into
+    # every workspace at checkout. With smudging skipped they arrive as small pointer files and
+    # `git status` stays clean, so nothing downloads until a recipe asks for it (`lfs.fetch`).
+    # Applied only where the gem writes files from Git itself; it is not applied to stash or
+    # apply, which must never swap a real file someone fetched for its pointer.
+    LFS_POINTERS_ONLY = { 'GIT_LFS_SKIP_SMUDGE' => '1' }.freeze
     METADATA = '.workspace.json'.freeze
     PR_METADATA = '.related-pr'.freeze
     attr_reader :id, :path
@@ -107,7 +113,7 @@ module Workspaces
 
       stash = save_changes
       begin
-        git!('-c', 'core.hooksPath=/dev/null', 'merge', '--ff-only', target, cwd: path)
+        git!('-c', 'core.hooksPath=/dev/null', 'merge', '--ff-only', target, cwd: path, env: LFS_POINTERS_ONLY)
       rescue CommandFailedError
         restore_changes(stash) if stash
         raise UpdateError, 'Could not fast-forward the workspace; local changes were restored'
@@ -117,8 +123,8 @@ module Workspaces
       { 'updated' => true, 'head' => target }
     end
 
-    def git!(*args, cwd: Config.repo_root)
-      output, status = Open3.capture2e(git_environment, 'git', *args, chdir: cwd.to_s)
+    def git!(*args, cwd: Config.repo_root, env: {})
+      output, status = Open3.capture2e(git_environment.merge(env), 'git', *args, chdir: cwd.to_s)
       raise_authentication_error!(output) unless status.success?
       raise CommandFailedError, "git #{args.join(' ')} failed:\n#{output}" unless status.success?
 
@@ -203,7 +209,7 @@ module Workspaces
       raise ArgumentError, 'Workspace branch must not start with a dash' if target_branch.start_with?('-')
 
       Config.worktrees_dir.mkpath
-      git!('-c', 'core.hooksPath=/dev/null', 'worktree', 'add', '-b', target_branch, path.to_s, sha)
+      git!('-c', 'core.hooksPath=/dev/null', 'worktree', 'add', '-b', target_branch, path.to_s, sha, env: LFS_POINTERS_ONLY)
     end
 
     def initialize_worktree!(source, target_branch)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.12
+  version: 0.1.14
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -71,6 +71,7 @@ files:
 - exe/workspaces
 - lib/workspaces.rb
 - lib/workspaces/backend.rb
+- lib/workspaces/build_history.rb
 - lib/workspaces/child_env.rb
 - lib/workspaces/cli.rb
 - lib/workspaces/command_runner.rb
@@ -89,6 +90,7 @@ files:
 - lib/workspaces/paths.rb
 - lib/workspaces/port_allocator.rb
 - lib/workspaces/presentation.rb
+- lib/workspaces/progress.rb
 - lib/workspaces/proxy_middleware.rb
 - lib/workspaces/recipe.rb
 - lib/workspaces/registry.rb