workspaces 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e22bcc91e0c7874f565156a5071aa07dae75e52eda5c9b5555f8d4a878f39aec
-  data.tar.gz: c72328bf47eb7aa1573221224cdc28f4f1e5f24e9539bf23adf8bfc970da7047
+  metadata.gz: 501f96e0f82b4dc9f30ec6682feb64329301b3ee888561e84e65941cff084ae7
+  data.tar.gz: 4ae2d5e24099d7638b349a332daaadf89813a96e37996c4f03c41c7baf2f7636
 SHA512:
-  metadata.gz: 58edd2f1a515d3ee18a69bfe2fe600ef2b26799689e35d94b57ab87251f634864a9e8a7d12415bdf1c5608dc461480dc38caa29c9f7db4305f62685ce739ac3e
-  data.tar.gz: d0cd9666cbdb265c23719d2de5aec54a6215b6db2f986ecbe061c27aae6578de5a8145a81669a382322ebc2618d3481edb947599d9edff7d76a68193b247e5c1
+  metadata.gz: 67865a47386639bfcff1218218bcf8f055c0b563d295d355d9667e1d8410da7a4981def707bc0f219f4179215b4839a689ec36bfa8bba90738ea92d7771b8ad7
+  data.tar.gz: 4be62e33d0f29d0c19751b61bd3b9d0dab8cf334314ce62bc5bcfe5f59569235c960b10647cf5bb7060705068db6c1489052b59a97b543c662750f66df3e6f4d

data/DESIGN.md

@@ -4,7 +4,7 @@
 
 Workspace list/create screen and per-workspace setup/status screen. Workspace identity is independent of PR provenance.
 
-GET is read-only. All creation and lifecycle controls submit same-origin POST forms. No source-reset or cleanup button exists. Workspace IDs, branches and filesystem paths wrap on narrow screens. Native labelled inputs and buttons are keyboard accessible; polling announces status without replacing form focus or making the entire log an ARIA live region.
+GET is read-only. All creation and lifecycle controls submit same-origin POST forms. Workspace IDs, branches and filesystem paths wrap on narrow screens. Native labelled inputs and buttons are keyboard accessible; polling announces status without replacing form focus or making the entire log an ARIA live region.
 
 ## Visual direction
 
@@ -41,9 +41,11 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
 ## Component primitives
 
 - **Creation form**: labelled branch, PR, and new-branch inputs with a primary create action
+- **Workspace inventory**: one row per managed workspace with a status distinct from backend running state, creation and last startup times, and a link to its detail page. Unknown timestamps are shown as unavailable, not inferred from recent setup.
 - **Status pill**: current workspace status as text
 - **Setup progress**: names and ordered states come from repository run steps; failures are highlighted. Restart shows the background launch and later readiness commands.
 - **Actions by state**: idle/stopped offers Start; active operations show progress without lifecycle buttons; failure offers Retry; ready offers Open workspace plus rebuild/restart/stop.
+- **PR source update**: a secondary Update from PR form only for PR-sourced workspaces; it fetches the latest PR head, fast-forwards the checkout, and preserves local edits without rebuilding or restarting. A persistent result message explains when rebuild is needed or when a retained stash needs manual recovery.
 - **Failure panel**: prominently above the log, with escaped error details and a matching retry action.
 - **PR page**: existing workspaces are primary; creating another is a collapsed secondary disclosure. Creation is primary only when none exist.
 - **Action buttons**: start, prepare/rebuild, restart server, stop server, and refresh
@@ -53,6 +55,8 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
 - **Log source switcher**: two native links inside one log panel, with current selection announced through `aria-current`; only the selected bounded log is loaded and refreshed. Setup is the default.
 - **Preview destination**: a small muted URL in Workspace details, visible before readiness; the primary Open workspace action remains reserved for ready servers.
 - **Editable environment**: labelled monospace multiline `NAME=value` control for non-secret recipe defaults and added workspace settings; busy state disables the fieldset and save button, values are escaped in HTML, other legacy overrides remain hidden. Omitted default names revert to recipe defaults; omitted added names are unset.
+- **Danger Zone**: isolated section on the detail page with explicit loss-of-uncommitted-and-untracked-work copy, an exact-workspace-ID confirmation field, and a destructive action. Deletion remains possible without JavaScript, is disabled while setup is busy, and never appears as a list-row action.
+- **Workspace favicon**: a small two-pane workspace mark served by the dashboard host. Use `--accent` blue for localhost and `--warning` gold for hosted origins so browser tabs signal the environment without relying on page text. The icon contains no workspace-specific data.
 
 ## Accessibility constraints
 

data/README.md

@@ -67,6 +67,25 @@ 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.
 
+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
+exact ID. Deletion stops the backend and force-removes the worktree, including
+uncommitted and untracked files; the branch and committed changes are preserved.
+Busy workspaces cannot be removed until their current operation finishes. This
+action is protected by the dashboard's same-origin POST check, but that check is
+not authentication—keep hosted deployments behind VPN or SSO.
+
+The dashboard favicon is blue for localhost and gold for hosted origins, helping
+distinguish local and hosted tabs.
+
+PR workspaces also offer **Update from PR** on their detail page. It fetches the
+latest PR head and fast-forwards the workspace branch only when the new head is
+a descendant of its current commit. Local tracked and untracked changes are
+temporarily stashed and restored (including staged state). On a restore conflict,
+the stash is retained for manual recovery. Updating the checkout does not run
+setup or restart the already-running backend; use Rebuild & restart afterward.
+
 The front door is not an authentication boundary. Its host and same-origin checks
 protect routing and POST actions, but a publicly reachable instance still needs
 access control such as VPN or SSO. Do not expose workspace backend ports directly.

data/lib/workspaces/cli.rb

@@ -137,16 +137,7 @@ module Workspaces
     end
 
     def remove(id, options)
-      registry.with_lock(id) do |workspace|
-        if !options[:force] && workspace.dirty?
-          raise ArgumentError,
-                'Workspace has uncommitted/untracked work; use --force to discard it'
-        end
-
-        Backend.new(id).stop!
-        workspace.remove!(force: options[:force])
-        StateStore.new(Config.state_file).delete(id)
-      end
+      registry.remove(id, force: options[:force])
       emit({ 'id' => id, 'removed' => true, 'branch_preserved' => true }, options)
     end
 

data/lib/workspaces/coordinator.rb

@@ -60,6 +60,17 @@ module Workspaces
       data.merge('presentation' => Presentation.new(data).to_h)
     end
 
+    def inventory
+      @registry.list.map do |workspace|
+        id = workspace.fetch('id')
+        entry = @state.get(id) || {}
+        busy = locked?(id)
+        workspace.merge('status' => resolve_status(id, entry.fetch('status', 'idle'), busy),
+                        'running' => !!Backend.new(id).running?, 'active' => busy,
+                        'started_at' => entry['started_at'])
+      end
+    end
+
     private
 
     def resolve_status(id, status, busy)
@@ -74,7 +85,9 @@ module Workspaces
       {
         'workspace_id' => id, 'status' => status, 'active' => busy,
         'message' => status == entry['status'] ? entry['message'] : status.capitalize,
-        'prepare_started_at' => entry['prepare_started_at'], 'updated_at' => entry['updated_at'],
+        'prepare_started_at' => entry['prepare_started_at'], 'started_at' => entry['started_at'],
+        'running' => !!Backend.new(id).running?, 'updated_at' => entry['updated_at'],
+        'source_update_message' => entry['source_update_message'],
         'completed_at' => entry['completed_at'], 'last_error' => entry['last_error'],
         'operation' => entry['operation'], 'failed_phase' => failure_phase(entry, status),
         'steps' => entry.fetch('steps', []),

data/lib/workspaces/dashboard/app.js

@@ -7,7 +7,7 @@
   const selectedLog = new URLSearchParams(window.location.search).get('log') === 'backend'
     ? 'backend'
     : 'setup';
-  const allowedActions = ['start', 'prepare', 'restart', 'stop'];
+  const allowedActions = ['start', 'prepare', 'restart', 'stop', 'update-pr'];
   let busy = root.dataset.busy === 'true';
   let started = Date.parse(root.dataset.started);
   let completed = Date.parse(root.dataset.completed);
@@ -18,6 +18,9 @@
     });
     if (window.WorkspaceEnvironment)
       window.WorkspaceEnvironment.toggleBusy(nextBusy);
+    node('remove-form').querySelectorAll('input, button').forEach((control) => {
+      control.disabled = nextBusy;
+    });
   }
 
   function renderActions(actions) {
@@ -75,6 +78,7 @@
     completed = Date.parse(data.completed_at);
     renderStatus(view);
     node('message').textContent = data.message || '';
+    node('source-update-message').textContent = data.source_update_message || '';
     node('progress').replaceChildren(...view.steps.map(renderStep));
     renderActions(view.actions);
     updateLog(data);
@@ -122,7 +126,8 @@
   }
 
   root.addEventListener('submit', (event) => {
-    if (event.target.id !== 'environment-form') toggleBusyState(true);
+    if (event.target.id !== 'environment-form' && event.target.id !== 'remove-form')
+      toggleBusyState(true);
     node('connection').textContent = 'Submitting…';
   });
 

data/lib/workspaces/dashboard/styles.css

@@ -312,6 +312,19 @@ fieldset:disabled {
   border-color: var(--border);
 }
 
+.button--danger {
+  background: var(--danger);
+  color: var(--bg);
+}
+
+.button:disabled { opacity: 0.55; cursor: not-allowed; transform: none; }
+
+.danger-zone { border-color: var(--danger); }
+.danger-zone h2 { margin-block-start: 0; color: var(--danger); }
+.danger-zone form { display: grid; justify-items: start; gap: var(--space-3); }
+.workspace-list { list-style: none; padding: 0; display: grid; gap: var(--space-3); }
+.workspace-list__item { display: grid; gap: var(--space-1); padding-block: var(--space-3); border-block-end: 1px solid var(--border); overflow-wrap: anywhere; }
+
 .button--success {
   background: color-mix(in oklab, var(--success) 22%, transparent);
   border-color: color-mix(in oklab, var(--success) 55%, var(--border));

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

@@ -22,6 +22,7 @@
       <div id="actions" class="workspace-actions"><% @presentation['actions'].each do |action| %><%= action_form(action) %><% end %></div>
     </div>
     <p id="connection" role="status"></p>
+    <p id="source-update-message" role="status"><%= field('source_update_message') %></p>
   </section>
   <section class="log-panel" aria-labelledby="log-title">
     <div class="log-header"><h2 id="log-title">Live <%= field('log_source') == 'backend' ? 'backend' : 'setup' %> log</h2><time id="updated"><%= field('updated_at') %></time></div>
@@ -48,6 +49,16 @@
       <p class="muted" id="environment-status" role="status" aria-live="polite"></p>
     </form>
   </section>
-  <details class="status-panel"><summary>Workspace details</summary><dl><dt>Preview URL</dt><dd><a class="detail-link" href="<%= escape(Config.preview_url(@id)) %>" target="_blank" rel="noopener noreferrer"><%= escape(Config.preview_url(@id)) %></a> <span class="muted">Available when ready</span></dd><dt>Branch</dt><dd><%= field('branch') %></dd><dt>Path</dt><dd><code><%= field('path') %></code></dd><dt>Related PR</dt><dd><%= escape(@snapshot.dig('related_pr', 'number') || 'None') %></dd></dl></details>
+  <details class="status-panel"><summary>Workspace details</summary><dl><dt>Preview URL</dt><dd><a class="detail-link" href="<%= escape(Config.preview_url(@id)) %>" target="_blank" rel="noopener noreferrer"><%= escape(Config.preview_url(@id)) %></a> <span class="muted">Available when ready</span></dd><dt>Branch</dt><dd><%= field('branch') %></dd><dt>Path</dt><dd><code><%= field('path') %></code></dd><dt>Related PR</dt><dd><%= escape(@snapshot.dig('related_pr', 'number') || 'None') %></dd><dt>Created</dt><dd><%= escape(@snapshot['created_at'] || 'Unavailable') %></dd><dt>Last startup</dt><dd><%= escape(@snapshot['started_at'] || 'Never') %></dd></dl></details>
+  <section class="status-panel danger-zone" aria-labelledby="danger-heading">
+    <h2 id="danger-heading">Danger Zone</h2>
+    <p>Deleting this workspace stops its server and removes its worktree. <strong>Discard uncommitted and untracked changes</strong> permanently. The branch and committed work are preserved.</p>
+    <form method="post" action="/workspaces/<%= @id %>/remove" id="remove-form">
+      <label for="confirm-id">Type <code><%= @id %></code> to confirm deletion</label>
+      <input id="confirm-id" name="confirm_id" required autocomplete="off" spellcheck="false" aria-describedby="remove-warning" <%= 'disabled' if @presentation['busy'] %>>
+      <p class="muted" id="remove-warning">This cannot restore uncommitted or untracked files.</p>
+      <button class="button button--danger" <%= 'disabled' if @presentation['busy'] %>>Delete workspace</button>
+    </form>
+  </section>
   <noscript><a href="/workspaces/<%= @id %>">Refresh status</a></noscript>
 </main>

data/lib/workspaces/dashboard_view.rb

@@ -21,8 +21,8 @@ module Workspaces
           <p><label>Start new branch from <input name="from" placeholder="HEAD"></label></p>
           <button class="button button--primary">Create workspace</button>
         </form></section>
-        <section class="status-panel"><h2>Managed workspaces</h2><ul>
-        #{workspaces.map { |workspace| "<li><a href=\"/workspaces/#{view.escape(workspace.fetch('id'))}\">#{view.escape(workspace.fetch('id'))}</a> — #{view.escape(workspace['branch'])}</li>" }.join}
+        <section class="status-panel"><h2>Managed workspaces</h2><ul class="workspace-list">
+        #{workspaces.map { |workspace| view.inventory_item(workspace) }.join}
         </ul></section></main>
       HTML
     end
@@ -35,6 +35,20 @@ module Workspaces
       new({}).render_checkout_authentication_error(path)
     end
 
+    def self.favicon
+      local = Config.public_uri.host.match?(/(?:\A|\.)localhost\z/i)
+      color = local ? '#4f8dff' : '#f1bb53'
+      <<~SVG
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Workspaces">
+          <rect x="3" y="3" width="58" height="58" rx="13" fill="#0f1524"/>
+          <rect x="11" y="13" width="42" height="38" rx="5" fill="none" stroke="#{color}" stroke-width="4"/>
+          <path d="M11 25h42M32 25v26" fill="none" stroke="#{color}" stroke-width="4"/>
+          <circle cx="18" cy="19" r="2" fill="#{color}"/>
+          <circle cx="25" cy="19" r="2" fill="#{color}"/>
+        </svg>
+      SVG
+    end
+
     def initialize(snapshot)
       @snapshot = snapshot
       @presentation = Presentation.new(snapshot).to_h
@@ -66,6 +80,7 @@ module Workspaces
                File.read(File.join(__dir__, 'dashboard/environment.js'), encoding: 'UTF-8')
       '<!doctype html><html lang="en"><head><meta charset="utf-8">' \
         '<meta name="viewport" content="width=device-width, initial-scale=1">' \
+        '<link rel="icon" type="image/svg+xml" href="/favicon.svg">' \
         "<title>#{escape(title)}</title><style>#{css}</style></head>" \
         "<body>#{body}<script>#{script}</script></body></html>"
     end
@@ -74,6 +89,20 @@ module Workspaces
       ERB::Util.html_escape(value.to_s)
     end
 
+    def inventory_item(workspace)
+      id = escape(Config.validate_id!(workspace.fetch('id')))
+      running = workspace['running'] ? 'Running' : 'Not running'
+      <<~HTML
+        <li class="workspace-list__item">
+          <a href="/workspaces/#{id}">#{id}</a>
+          <span class="muted">#{escape(workspace['branch'])}</span>
+          <span>#{running} · #{escape(workspace['status'] || 'idle')}#{workspace['active'] ? ' (busy)' : ''}</span>
+          <span class="muted">Created <time datetime="#{escape(workspace['created_at'])}">#{escape(workspace['created_at'] || 'Unavailable')}</time></span>
+          <span class="muted">Last startup <time datetime="#{escape(workspace['started_at'])}">#{escape(workspace['started_at'] || 'Never')}</time></span>
+        </li>
+      HTML
+    end
+
     private
 
     def field(name)

data/lib/workspaces/environment_overrides.rb

@@ -54,8 +54,9 @@ module Workspaces
     end
 
     def editable_values(defaults)
-      load_file(file_path)
-      defaults.merge(load_file(editable_file_path).reject { |name, _| sensitive_name?(name) })
+      legacy = load_file(file_path).slice(*defaults.keys)
+      editable = load_file(editable_file_path).reject { |name, _| sensitive_name?(name) }
+      defaults.merge(legacy).merge(editable)
     end
 
     def replace_editable(text, defaults:)

data/lib/workspaces/front_door.rb

@@ -9,7 +9,7 @@ require_relative 'environment_overrides'
 module Workspaces
   class FrontDoor
     WORKSPACE_ROUTE = %r{\A/workspaces/([a-z0-9]+(?:-[a-z0-9]+)*)
-                          (?:/(status|start|prepare|restart|stop|environment))?\z}x
+                          (?:/(status|start|prepare|restart|stop|remove|update-pr|environment))?\z}x
 
     def initialize(coordinator: Coordinator.new, registry: Registry.new)
       @coordinator = coordinator
@@ -35,6 +35,7 @@ module Workspaces
     private
 
     def route(request)
+      return favicon(request) if request.path_info == '/favicon.svg'
       return index(request) if ['/', '/workspaces'].include?(request.path_info)
       return create(request) if request.path_info == '/workspaces/create'
       pr_match = %r{\A/pr/([1-9][0-9]*)\z}.match(request.path_info)
@@ -43,6 +44,12 @@ module Workspaces
       workspace_route(request)
     end
 
+    def favicon(request)
+      return response(405, 'Use GET or HEAD') unless safe?(request)
+
+      response(200, DashboardView.favicon, type: 'image/svg+xml', head: request.head?)
+    end
+
     def workspace_route(request)
       match = WORKSPACE_ROUTE.match(request.path_info)
       return response(404, 'Not found. Visit /workspaces.') unless match
@@ -69,7 +76,7 @@ module Workspaces
     def index(request)
       return response(405, 'Use GET or HEAD') unless safe?(request)
 
-      response(200, DashboardView.index(@registry.list), type: 'text/html', head: request.head?)
+      response(200, DashboardView.index(@coordinator.inventory), type: 'text/html', head: request.head?)
     end
 
     def action_request(request, id, action)
@@ -77,6 +84,8 @@ module Workspaces
       return status_response(request, id, action) if action.nil? || action == 'status'
       return response(405, 'Use POST') unless request.post?
       return response(403, 'Actions require the configured dashboard origin') unless same_origin?(request)
+      return remove(request, id) if action == 'remove'
+      return update_pr(id) if action == 'update-pr'
 
       perform_action(id, action)
       redirect(Config.dashboard_url(id))
@@ -126,6 +135,26 @@ module Workspaces
       end
     end
 
+    def remove(request, id)
+      unless request.media_type == 'application/x-www-form-urlencoded'
+        return response(415, 'Deletion requires a form-encoded confirmation')
+      end
+      return response(413, 'Deletion confirmation is too large') if request.content_length.to_i > 512
+      return response(422, 'Type the exact workspace ID to confirm deletion') unless request.POST['confirm_id'] == id
+
+      @registry.remove(id, force: true)
+      redirect("#{Config.public_origin}/workspaces")
+    rescue ArgumentError, Worktree::CommandFailedError, SystemCallError
+      response(409, 'Workspace was not removed. Check the server logs and retry when safe.')
+    end
+
+    def update_pr(id)
+      @registry.update_pr(id)
+      redirect(Config.dashboard_url(id))
+    rescue Worktree::UpdateError
+      redirect(Config.dashboard_url(id))
+    end
+
     def create(request)
       return response(405, 'Use POST') unless request.post?
       return response(403, 'Creation requires the configured dashboard origin') unless same_origin?(request)

data/lib/workspaces/presentation.rb

@@ -50,10 +50,16 @@ module Workspaces
 
     def actions
       return [] if busy?
-      return %w(prepare restart stop).map { |key| action(key, false) } if status == 'ready'
-      return [retry_action] if %w(error interrupted).include?(status)
+      available = if status == 'ready'
+                    %w(prepare restart stop).map { |key| action(key, false) }
+                  elsif %w(error interrupted).include?(status)
+                    [retry_action]
+                  else
+                    [action('start', true)]
+                  end
+      available << { 'key' => 'update-pr', 'label' => 'Update from PR', 'primary' => false } if @snapshot.dig('source', 'kind') == 'pr'
+      available
 
-      [action('start', true)]
     end
 
     def retry_action

data/lib/workspaces/registry.rb

@@ -1,5 +1,6 @@
 require_relative 'worktree'
 require_relative 'state_store'
+require_relative 'backend'
 
 module Workspaces
   class Registry
@@ -35,6 +36,31 @@ module Workspaces
       end
     end
 
+    def remove(id, force: false)
+      with_lock(id) do |workspace|
+        raise ArgumentError, 'Workspace has uncommitted/untracked work' if !force && workspace.dirty?
+
+        Backend.new(id).stop!
+        workspace.remove!(force: force)
+        StateStore.new(Config.state_file).delete(id)
+      end
+    end
+
+    def update_pr(id)
+      with_lock(id) do |workspace|
+        result = workspace.update_from_pr!
+        message = result['updated'] ? 'PR checkout updated. Rebuild & restart to run the new code.' : 'PR checkout is already current.'
+        StateStore.new(Config.state_file).set(id, 'source_update_message' => message,
+                                                  'source_updated_at' => Time.now.utc.iso8601)
+        result
+      rescue Worktree::UpdateError, Worktree::CommandFailedError => e
+        message = e.is_a?(Worktree::CommandFailedError) ? 'Could not fetch or update the PR checkout; local files were not intentionally discarded' : e.message
+        StateStore.new(Config.state_file).set(id, 'source_update_message' => message,
+                                                  'source_updated_at' => Time.now.utc.iso8601)
+        raise Worktree::UpdateError, message
+      end
+    end
+
     private
 
     def describe_directory(directory, number)

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.1'
+  VERSION = '0.1.3'
 end

data/lib/workspaces/worktree.rb

@@ -9,6 +9,7 @@ module Workspaces
   class Worktree
     class CommandFailedError < StandardError; end
     class AuthenticationError < CommandFailedError; end
+    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)
     METADATA = '.workspace.json'.freeze
@@ -90,6 +91,32 @@ module Workspaces
       git!(*args, path.to_s)
     end
 
+    def update_from_pr!
+      require_owned!
+      source = metadata.fetch('source')
+      raise UpdateError, 'Only a PR workspace can be updated from a PR' unless source['kind'] == 'pr'
+      raise UpdateError, 'Resolve the retained workspace update stash before updating again' if update_stash?
+
+      number = source.fetch('number')
+      raise UpdateError, 'Invalid PR number in workspace metadata' unless number.to_s.match?(/\A[1-9][0-9]*\z/)
+
+      target = fetch_pr_head(number)
+      current = git!('rev-parse', 'HEAD', cwd: path)
+      raise UpdateError, 'Workspace branch has diverged from the PR; no files were changed' unless ancestor?(current, target)
+      return { 'updated' => false, 'head' => current } if current == target
+
+      stash = save_changes
+      begin
+        git!('-c', 'core.hooksPath=/dev/null', 'merge', '--ff-only', target, cwd: path)
+      rescue CommandFailedError
+        restore_changes(stash) if stash
+        raise UpdateError, 'Could not fast-forward the workspace; local changes were restored'
+      end
+
+      restore_changes(stash) if stash
+      { 'updated' => true, 'head' => target }
+    end
+
     def git!(*args, cwd: Config.repo_root)
       output, status = Open3.capture2e(git_environment, 'git', *args, chdir: cwd.to_s)
       raise_authentication_error!(output) unless status.success?
@@ -100,8 +127,61 @@ module Workspaces
 
     private
 
+    def fetch_pr_head(number)
+      ref = "refs/workspaces/updates/#{id}"
+      git!('fetch', 'origin', "+pull/#{number}/head:#{ref}", cwd: path)
+      target = git!('rev-parse', '--verify', "#{ref}^{commit}", cwd: path)
+      git!('update-ref', '-d', ref, cwd: path)
+      target
+    end
+
+    def ancestor?(current, target)
+      _, status = Open3.capture2e(git_environment, 'git', 'merge-base', '--is-ancestor', current, target,
+                                  chdir: path.to_s)
+      return true if status.exitstatus == 0
+      return false if status.exitstatus == 1
+
+      raise CommandFailedError, 'Unable to check PR ancestry'
+    end
+
+    def save_changes
+      return nil unless dirty?
+
+      previous = git!('rev-parse', '--verify', '-q', 'refs/stash', cwd: path) if stash_exists?
+      git!('stash', 'push', '--include-untracked', '-m', "workspaces update #{id}", cwd: path)
+      current = git!('rev-parse', '--verify', 'refs/stash', cwd: path)
+      raise UpdateError, 'Unable to save workspace changes; check the worktree and stash before retrying' if current == previous || dirty?
+
+      current
+    end
+
+    def stash_exists?
+      _, status = Open3.capture2e(git_environment, 'git', 'rev-parse', '--verify', '-q', 'refs/stash',
+                                  chdir: path.to_s)
+      status.success?
+    end
+
+    def update_stash?
+      git!('stash', 'list', '--format=%gs', cwd: path).lines.any? do |line|
+        line.chomp.end_with?("workspaces update #{id}")
+      end
+    end
+
+    def restore_changes(stash)
+      return unless stash
+
+      begin
+        git!('stash', 'apply', '--index', stash, cwd: path)
+      rescue CommandFailedError
+        raise UpdateError, "Workspace changes could not be reapplied. Stash #{stash} is retained for manual recovery; resolve worktree conflicts before retrying"
+      end
+      return unless git!('rev-parse', 'refs/stash', cwd: path) == stash
+
+      git!('stash', 'drop', 'stash@{0}', cwd: path)
+    end
+
     def git_environment
-      { 'GIT_TERMINAL_PROMPT' => '0', 'GIT_ASKPASS' => '/bin/false', 'SSH_ASKPASS' => '/bin/false',
+      { 'GIT_MASTER' => '1', 'GIT_TERMINAL_PROMPT' => '0', 'GIT_ASKPASS' => '/bin/false', 'SSH_ASKPASS' => '/bin/false',
         'GCM_INTERACTIVE' => 'Never', 'GIT_SSH_COMMAND' => noninteractive_ssh }
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack