workspaces 0.1.16 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5377d0d4a49b5a0b585540ddc02e4eeaaeb3e34a8a26dba5ce4db2107c85334
-  data.tar.gz: d880d6274c7a79ca45f9fd39232310083c4709d5b3a3bdf630d6eee716563278
+  metadata.gz: 9f662b3baa05bd9cd6a684906e2bf2d75d663dfa493fd684ef1090adb0095276
+  data.tar.gz: 2265a4ddeeae587c04b2eae5e8ed0e8a7f5f64988bb9c22c0f1f4c9202c30b9f
 SHA512:
-  metadata.gz: aeb8a8dbd6e618499c3831d711734df8eb930f88656c0f2f66617f9835ddd1d994ef39c25362d784697cef44478847ed1df9d4ceb382a37066209d2bb427b9aa
-  data.tar.gz: 6fe026cae101124808e962b0280c64a4d851665b02789dad6b6eceeea7dcf0147d46a11ee21c7df261671c2369c606e01f3baee45ed28efbe47fd13d5ac8fefe
+  metadata.gz: 3cea009527f192e61a8c14a2f9642e7f67d0d58118e2f13884a28c68d5b10c17ca12c98dfba24af32618ebae87e4f3f34645a10048ce110ec395424be1dda5c0
+  data.tar.gz: 496afa3b947a7c21a58f9e66f9f542b3146ce327fabad2b5633bd58f63d089a3e8ad965420e251e0589213acffc1219845625c9ba8377d42d6b59e9a5c608d8e

data/DESIGN.md

@@ -61,6 +61,7 @@ Restrained tooling UI: dark elevated panels, compact spacing rhythm, clear statu
   - `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.
 - **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.
+- **Sleeping**: a workspace asleep is its own state (`sleeping`), distinct from stopped and failed. The lead reads "Your workspace is asleep", says files and data are kept and that opening the preview wakes it, and offers one **Wake workspace** button. A ready workspace shows one muted line, "Sleeps after N min without preview traffic", or "Kept awake" when exempt. **Keep awake** / **Allow sleep** are subtle workspace controls. A waking workspace is simply 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

data/README.md

@@ -114,6 +114,58 @@ usually takes, count the running step by how much of its usual time has passed,
 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.
 
+## Sleeping idle workspaces
+
+A ready workspace that sees no preview traffic for a while is put to sleep: its server (the
+managed process group, and nothing shared such as PostgreSQL or Redis) is stopped, and the
+front door keeps answering on the same preview URL. The worktree, database, dependencies, built
+assets, environment settings and build history are untouched. The first request to a sleeping
+preview wakes it, waits for readiness and then forwards that request.
+
+```sh
+WORKSPACES_SLEEP_AFTER_MINUTES=30   # default; 15 also works; 0 switches sleeping off
+WORKSPACES_WAKE_TIMEOUT_SECONDS=90  # how long the first request waits for a wake
+WORKSPACES_SLEEP_SWEEP_SECONDS=30   # how often idle workspaces are looked for
+bundle exec workspaces keep-awake <workspace-id>          # never sleep this workspace
+bundle exec workspaces keep-awake <workspace-id> --off    # allow sleep again
+```
+
+The dashboard shows when a workspace sleeps, says "asleep" with a **Wake workspace** button, and has
+**Keep awake** / **Allow sleep** under Workspace controls. The setting is stored with the workspace.
+
+What counts as activity:
+
+- Preview requests do. Dashboard and status polling never reach the preview and do not count.
+- `/health` and `/up` never count and never wake a workspace. List more background polling under
+  `sleep.ignore_paths` (globs on the request path) in `.workspaces.yml`:
+
+  ```yaml
+  sleep:
+    ignore_paths:
+      - /api/heartbeat
+  ```
+
+- A request in flight holds the workspace awake until its response body is finished. Streamed
+  responses hold it until the body is closed. Streaming and upgraded connections are not newly
+  supported by the proxy; this only means the ones it already serves are never cut off.
+- Work the proxy cannot see (background jobs, scheduled tasks) is not activity. A workspace that
+  runs such work needs `keep-awake`, or `WORKSPACES_SLEEP_AFTER_MINUTES=0`.
+
+How waking behaves:
+
+- Only an intentionally sleeping workspace wakes. A workspace stopped by hand, failed, or still
+  preparing is never started by traffic; a GET still lands on the dashboard as before.
+- Simultaneous first requests share one wake and start one server. A request is sent upstream
+  once, never replayed, and keeps its method and body.
+- A wake runs only the server and readiness steps. If a step before the server changed in
+  `.workspaces.yml` since the workspace was prepared, it runs the full preparation instead.
+- A wake that fails or runs past the timeout answers `503` with `Retry-After`, a link to the
+  dashboard, and the failure in the workspace's status and logs. It is not retried in a loop.
+- Sleeping and waking use the same per-workspace lock as start, stop, restart and rebuild, so
+  they cannot overlap. After a front-door restart a sleeping workspace stays asleep, a sleep cut
+  short is finished, and a wake cut short shows as interrupted.
+- Idle clocks live in the front door's memory, so a restart gives every workspace a fresh idle period.
+
 ## Serve the dashboard and previews
 
 Run `serve` in a separate terminal using the **same project root and `WORKSPACES_HOME`**

data/lib/workspaces/activity_tracker.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Workspaces
+  # Remembers when each workspace last saw preview traffic and how many requests are in flight.
+  # Only the front door that proxies the traffic can know this, so it lives in memory.
+  #
+  # A request holds a Lease from the moment it is accepted until its response is finished, and a
+  # workspace with any lease out is never put to sleep. The decision to sleep and new requests meet
+  # at one mutex: once a workspace is chosen for sleep, `acquire` refuses until the sleep is over,
+  # so a request can never slip in between "nothing in flight" and "server stopped".
+  class ActivityTracker
+    class Lease
+      def initialize(tracker, id, counted)
+        @tracker = tracker
+        @id = id
+        @counted = counted
+        @released = false
+      end
+
+      def release
+        @tracker.send(:release, self, @id, @counted)
+      end
+
+      def released?
+        @released
+      end
+
+      def mark_released!
+        was = @released
+        @released = true
+        !was
+      end
+    end
+
+    def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @clock = clock
+      @mutex = Mutex.new
+      @last_activity = {}
+      @in_flight = Hash.new(0)
+      @sleeping = {}
+    end
+
+    # `counted: false` is for traffic that must not keep a workspace awake (configured background
+    # polling): it still holds a lease, so the server is not stopped under it.
+    # Returns nil while the workspace is being put to sleep.
+    def acquire(id, counted: true)
+      @mutex.synchronize do
+        return nil if @sleeping[id]
+
+        @in_flight[id] += 1
+        @last_activity[id] = @clock.call if counted
+        Lease.new(self, id, counted)
+      end
+    end
+
+    def touch(id)
+      @mutex.synchronize { @last_activity[id] = @clock.call }
+    end
+
+    # Seconds since the last counted activity. A workspace seen for the first time starts its idle
+    # clock now, which is also how the clocks restart after the front door does.
+    def idle_for(id)
+      @mutex.synchronize { @clock.call - (@last_activity[id] ||= @clock.call) }
+    end
+
+    def in_flight(id)
+      @mutex.synchronize { @in_flight[id] }
+    end
+
+    # Runs the block only if the workspace has been idle for `threshold` seconds with nothing in
+    # flight, and keeps new requests out until it returns. Returns the block's value, or false.
+    def sleep_if_idle(id, threshold)
+      @mutex.synchronize do
+        return false if @sleeping[id] || @in_flight[id].positive?
+        return false if @clock.call - (@last_activity[id] ||= @clock.call) < threshold
+
+        @sleeping[id] = true
+      end
+      begin
+        yield
+      ensure
+        @mutex.synchronize { @sleeping.delete(id) }
+      end
+    end
+
+    def forget(id)
+      @mutex.synchronize do
+        @last_activity.delete(id)
+        @in_flight.delete(id)
+        @sleeping.delete(id)
+      end
+    end
+
+    private
+
+    def release(lease, id, counted)
+      @mutex.synchronize do
+        return false unless lease.mark_released!
+
+        @in_flight[id] -= 1
+        @in_flight.delete(id) if @in_flight[id] <= 0
+        @last_activity[id] = @clock.call if counted
+        true
+      end
+    end
+  end
+end

data/lib/workspaces/cli.rb

@@ -8,13 +8,16 @@ require_relative 'front_door'
 require_relative 'proxy_middleware'
 require_relative 'tls'
 require_relative 'child_env'
+require_relative 'activity_tracker'
+require_relative 'sleeper'
+require_relative 'duration_format'
 
 module Workspaces
   class Cli
     COMMANDS = {
       'serve' => :serve, 'create' => :create, 'list' => :list, 'show' => :show,
       'start' => :lifecycle, 'prepare' => :lifecycle, 'restart' => :lifecycle,
-      'stop' => :stop, 'remove' => :remove, 'resume' => :resume, 'help' => :help
+      'stop' => :stop, 'remove' => :remove, 'resume' => :resume, 'keep-awake' => :keep_awake, 'help' => :help
     }.freeze
     def self.run(argv)
       new.run(argv.dup)
@@ -85,6 +88,7 @@ module Workspaces
       parser.on('--from REF') { |value| options[:from] = value }
       parser.on('--json') { options[:json] = true }
       parser.on('--force') { options[:force] = true }
+      parser.on('--off') { options[:off] = true }
     end
 
     def parse_tls_options(parser, options)
@@ -110,7 +114,20 @@ module Workspaces
       puts "Dashboard: #{Config.public_origin}/workspaces"
       puts "Managed directory: #{Config.worktrees_dir}"
       print_tls_exports(tls)
-      Rackup::Handler::Puma.run(FrontDoor.new, **puma_options(tls))
+      tracker = ActivityTracker.new
+      sleeper = Sleeper.new(coordinator: coordinator, tracker: tracker).start
+      puts sleep_banner
+      begin
+        Rackup::Handler::Puma.run(FrontDoor.new(coordinator: coordinator, registry: registry, tracker: tracker),
+                                  **puma_options(tls))
+      ensure
+        sleeper.stop
+      end
+    end
+
+    def sleep_banner
+      seconds = Config.sleep_after_seconds
+      seconds ? "Idle workspaces sleep after #{DurationFormat.call(seconds)} without preview traffic" : 'Idle sleep is off'
     end
 
     def print_tls_exports(tls)
@@ -177,10 +194,15 @@ module Workspaces
     end
 
     def stop(id, options)
-      registry.with_lock(id) do
-        Backend.new(id).stop!
-        StateStore.new(Config.state_file).set(id, 'status' => 'stopped', 'message' => 'Server stopped')
-      end
+      coordinator.stop(id)
+      emit(coordinator.snapshot(id), options)
+    end
+
+    # Exempts a workspace from sleeping (or, with --off, lets it sleep again).
+    def keep_awake(id, options)
+      raise ArgumentError, 'keep-awake needs a workspace ID' unless id
+
+      coordinator.keep_awake(id, !options[:off])
       emit(coordinator.snapshot(id), options)
     end
 
@@ -220,7 +242,7 @@ 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] | ' \
-        'resume ID [--from STEP | --only STEP] [--json] | stop ID | ' \
+        'resume ID [--from STEP | --only STEP] [--json] | stop ID | keep-awake ID [--off] | ' \
         'exec ID -- COMMAND... | remove ID [--force]'
     end
 

data/lib/workspaces/config.rb

@@ -17,6 +17,35 @@ module Workspaces
     DEFAULT_SUBDOMAIN_PREFIX = 'ws-'
     DEFAULT_FRONT_DOOR_PORT = 4747
     BACKEND_PORT_RANGE = (30_000..30_999)
+    DEFAULT_SLEEP_AFTER_MINUTES = 30
+    DEFAULT_WAKE_TIMEOUT_SECONDS = 90
+    DEFAULT_SLEEP_SWEEP_SECONDS = 30
+
+    # Seconds a ready workspace may go without preview traffic before it is put to sleep, or nil when
+    # sleeping is switched off (WORKSPACES_SLEEP_AFTER_MINUTES=0). Fractions of a minute are allowed.
+    def self.sleep_after_seconds
+      minutes = positive_number('WORKSPACES_SLEEP_AFTER_MINUTES', DEFAULT_SLEEP_AFTER_MINUTES, allow_zero: true)
+      minutes.zero? ? nil : minutes * 60
+    end
+
+    # How long the first request to a sleeping preview waits for the server to be ready.
+    def self.wake_timeout_seconds
+      positive_number('WORKSPACES_WAKE_TIMEOUT_SECONDS', DEFAULT_WAKE_TIMEOUT_SECONDS)
+    end
+
+    def self.sleep_sweep_seconds
+      positive_number('WORKSPACES_SLEEP_SWEEP_SECONDS', DEFAULT_SLEEP_SWEEP_SECONDS)
+    end
+
+    def self.positive_number(name, default, allow_zero: false)
+      value = Float(ENV.fetch(name, default.to_s))
+      return value if value.finite? && (value.positive? || (allow_zero && value.zero?))
+
+      raise ArgumentError, "#{name} must be a#{allow_zero ? ' non-negative' : ' positive'} number"
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "#{name} must be a#{allow_zero ? ' non-negative' : ' positive'} number"
+    end
+    private_class_method :positive_number
 
     def self.front_door_port
       Integer(ENV.fetch('WORKSPACES_PORT', DEFAULT_FRONT_DOOR_PORT))

data/lib/workspaces/coordinator.rb

@@ -22,6 +22,12 @@ module Workspaces
     end
 
     def start(id, force: false, preset: nil, set: {}, unset: [])
+      if !force && sleeping?(id)
+        return wake(id) unless preset || !set.empty? || !unset.empty?
+
+        return launch(id, restart: true, force: true, prelaunch: settings_update(id, preset, set, unset))
+      end
+
       launch(id, restart: false, force: force, prelaunch: settings_update(id, preset, set, unset))
     end
 
@@ -49,7 +55,7 @@ module Workspaces
     end
 
     def update_environment(id, set:, remove:)
-      restart = Backend.new(id).running?
+      restart = Backend.new(id).running? || sleeping?(id)
       launch(id, restart: restart, force: true,
                  prelaunch: lambda { |_workspace|
                    Recipe.new
@@ -58,7 +64,7 @@ module Workspaces
     end
 
     def replace_editable_environment(id, text:)
-      restart = Backend.new(id).running?
+      restart = Backend.new(id).running? || sleeping?(id)
       launch(id, restart: restart, force: true,
                  prelaunch: lambda { |_workspace|
                    defaults = Recipe.new.default_editable_env
@@ -66,6 +72,105 @@ module Workspaces
                  })
     end
 
+    # Stops an idle workspace's server and keeps everything else: worktree, database, dependencies,
+    # built assets, settings and build history. Returns true when it slept. Does nothing (false) while
+    # the workspace is busy, is kept awake, is not running, or is already asleep.
+    def sleep!(id)
+      @registry.find(id)
+      lock = acquire_lock(id)
+      return false unless lock
+
+      begin
+        entry = @state.get(id) || {}
+        return false unless sleepable?(id, entry)
+
+        update(id, 'sleep_state' => 'sleeping', 'slept_at' => now)
+        begin
+          Backend.new(id).stop!
+        rescue StandardError
+          update(id, 'sleep_state' => nil, 'slept_at' => nil)
+          raise
+        end
+        true
+      ensure
+        lock.close
+      end
+    end
+
+    # Starts a sleeping workspace's server again and returns at once; the caller watches for readiness.
+    # Only a workspace that is intentionally asleep is woken: one that was stopped by hand, failed,
+    # or is already starting is left alone (false). Concurrent callers share one wake because only
+    # the one holding the workspace lock gets past the check.
+    def wake(id)
+      workspace = @registry.find(id)
+      lock = acquire_lock(id)
+      return false unless lock
+
+      entry = @state.get(id) || {}
+      if entry['sleep_state'] != 'sleeping' || Backend.new(id).running?
+        lock.close
+        return false
+      end
+
+      restart = preparation_current?(entry)
+      publish_starting(id, restart, extra: { 'sleep_state' => 'waking', 'message' => 'Waking workspace' })
+      spawn_worker(workspace, restart, lock)
+      true
+    rescue StandardError
+      lock&.close unless lock&.closed?
+      raise
+    end
+
+    # Stops the server by hand. A workspace stopped this way is not asleep, so traffic never wakes it.
+    def stop(id)
+      @registry.with_lock(id) do
+        Backend.new(id).stop!
+        @state.set(id, 'status' => 'stopped', 'message' => 'Server stopped', 'sleep_state' => nil, 'slept_at' => nil)
+      end
+    end
+
+    def keep_awake(id, enabled)
+      @registry.find(id)
+      @state.set(id, 'keep_awake' => !!enabled)
+      !!enabled
+    end
+
+    def sleeping?(id)
+      (@state.get(id) || {})['sleep_state'] == 'sleeping'
+    end
+
+    # :sleeping, :waking (a wake is running), or nil.
+    def sleep_phase(id)
+      case (@state.get(id) || {})['sleep_state']
+      when 'sleeping' then :sleeping
+      when 'waking' then locked?(id) ? :waking : nil
+      end
+    end
+
+    def status_of(id)
+      entry = @state.get(id) || {}
+      resolve_status(id, entry, locked?(id))
+    end
+
+    # Workspaces that look ready, are not kept awake and are not asleep. A cheap read of the state
+    # file; `sleep!` checks everything again under the workspace lock.
+    def sleep_candidates
+      @state.all.filter_map do |id, entry|
+        id if entry['status'] == 'ready' && !entry['keep_awake'] && entry['sleep_state'].nil?
+      end
+    end
+
+    # Run once when a front door starts. A sleep that was cut short is finished, and a wake that was
+    # cut short is cleared, so the workspace reads as interrupted rather than as waking forever.
+    def reconcile_sleep
+      @state.all.each do |id, entry|
+        case entry['sleep_state']
+        when 'sleeping' then finish_interrupted_sleep(id)
+        when 'waking' then @state.set(id, 'sleep_state' => nil) unless locked?(id)
+        end
+      end
+    end
+
     def wait(id)
       workers_mutex.synchronize { workers[id] }&.value
       snapshot(id)
@@ -77,7 +182,7 @@ module Workspaces
       workspace = @registry.find(id)
       entry = @state.get(id) || {}
       busy = locked?(id)
-      status = resolve_status(id, entry.fetch('status', 'idle'), busy)
+      status = resolve_status(id, entry, busy)
       data = workspace.describe.merge(snapshot_fields(id, entry, busy, status, log, include_log))
       data.merge('presentation' => Presentation.new(data).to_h)
     end
@@ -87,7 +192,7 @@ module Workspaces
         id = workspace.fetch('id')
         entry = @state.get(id) || {}
         busy = locked?(id)
-        workspace.merge('status' => resolve_status(id, entry.fetch('status', 'idle'), busy),
+        workspace.merge('status' => resolve_status(id, entry, busy),
                         'running' => !!Backend.new(id).running?, 'active' => busy,
                         'started_at' => entry['started_at'])
       end
@@ -103,17 +208,43 @@ module Workspaces
       end
     end
 
-    def resolve_status(id, status, busy)
+    def resolve_status(id, entry, busy)
+      status = entry.fetch('status', 'idle')
       return busy ? status : 'interrupted' if ACTIVE.include?(status)
       return status if status == 'error'
       return 'ready' if Backend.new(id).running?
+      return 'sleeping' if entry['sleep_state'] == 'sleeping'
 
       status == 'ready' ? 'stopped' : status
     end
 
+    def sleepable?(id, entry)
+      entry['status'] == 'ready' && !entry['keep_awake'] && entry['sleep_state'].nil? && Backend.new(id).running?
+    end
+
+    # What was prepared still matches the recipe, so waking only needs the server and readiness steps.
+    # A workspace prepared before this was recorded is trusted.
+    def preparation_current?(entry)
+      recorded = entry['prepared_digest']
+      recorded.nil? || recorded == Recipe.new.preparation_digest
+    end
+
+    def finish_interrupted_sleep(id)
+      lock = acquire_lock(id)
+      return unless lock
+
+      begin
+        Backend.new(id).stop! if Backend.new(id).running?
+      ensure
+        lock.close
+      end
+    end
+
     def snapshot_fields(id, entry, busy, status, log, include_log)
       {
         'workspace_id' => id, 'status' => status, 'active' => busy,
+        'sleeping' => status == 'sleeping', 'slept_at' => entry['slept_at'],
+        'keep_awake' => !!entry['keep_awake'], 'sleep_after_seconds' => Config.sleep_after_seconds,
         'message' => status == entry['status'] ? entry['message'] : status.capitalize,
         'prepare_started_at' => entry['prepare_started_at'], 'started_at' => entry['started_at'],
         'running' => !!Backend.new(id).running?, 'updated_at' => entry['updated_at'],
@@ -191,18 +322,20 @@ module Workspaces
       end
     end
 
-    def publish_starting(id, restart)
+    def publish_starting(id, restart, extra: {})
       recipe = Recipe.new
       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',
+      update(id, {
+                 'status' => 'preparing', 'message' => restart ? 'Restarting application' : 'Preparing workspace',
                  'steps' => steps, 'estimates' => BuildHistory.estimates(steps.map { |step| step['key'] }),
                  'operation' => restart ? 'restart' : 'prepare', 'rerun_keys' => nil, 'failed_phase' => nil,
                  'prepare_started_at' => now, 'completed_at' => nil, 'last_error' => nil,
-                 'total_seconds' => nil)
+                 'total_seconds' => nil, 'sleep_state' => nil, 'slept_at' => nil
+               }.merge(extra))
     end
 
     def spawn_worker(workspace, restart, lock, plan: nil)
@@ -241,8 +374,10 @@ module Workspaces
       total = elapsed_since(started)
       # 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 = { 'status' => 'ready', 'message' => 'Workspace ready', 'completed_at' => now, 'total_seconds' => total,
+                     'sleep_state' => nil }
       attributes['port'] = port if port
+      attributes['prepared_digest'] = Recipe.new.preparation_digest if plan.nil? && !restart
       update(id, attributes)
       record_run(id, 'complete', total)
     end
@@ -254,7 +389,7 @@ module Workspaces
       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' => total)
+                 'total_seconds' => total, 'sleep_state' => nil)
       record_run(id, 'failed', total)
     end
 

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', 'resume', 'stop', 'update-pr'];
+  const allowedActions = ['start', 'prepare', 'restart', 'resume', 'stop', 'update-pr', 'keep-awake', 'allow-sleep'];
   let busy = root.dataset.busy === 'true';
   let started = Date.parse(root.dataset.started);
   let completed = Date.parse(root.dataset.completed);
@@ -245,9 +245,23 @@
       window.WorkspaceEnvironment.setSubmitLabel(view.environment_submit);
   }
 
+  function sleepNote(view) {
+    const sleep = view.sleep;
+    if (!sleep) return '';
+    if (sleep.keep_awake) return 'Kept awake: this workspace will not sleep when idle.';
+    if (view.state !== 'ready') return '';
+    const minutes = Math.round(sleep.after_seconds / 60);
+    return 'Sleeps after ' + (minutes >= 1 ? minutes + ' min' : Math.round(sleep.after_seconds) + ' s') + ' without preview traffic.';
+  }
+
   function renderLead(view) {
     node('status').textContent = view.headline || view.title;
     node('summary').textContent = view.summary || '';
+    const note = node('sleep-note');
+    if (note) {
+      note.textContent = sleepNote(view);
+      note.hidden = !note.textContent;
+    }
     renderProgress(view.progress);
     const title = node('environment-title');
     if (title && view.environment_title) title.textContent = view.environment_title;

data/lib/workspaces/dashboard/styles.css

@@ -266,6 +266,10 @@ h1 {
   background: var(--success);
 }
 
+.status-pill[data-status='sleeping'] .status-dot {
+  background: var(--muted);
+}
+
 .status-pill[data-status='error'] .status-dot,
 .status-pill[data-status='interrupted'] .status-dot,
 .status-pill[data-status='stopped'] .status-dot {

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

@@ -19,6 +19,7 @@
       <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>
       <div id="lead-action" class="lead__action"><%= lead_action_form(@presentation['lead_action']) %></div>
     </div>
+    <p id="sleep-note" class="muted" <%= 'hidden' if sleep_note.empty? %>><%= escape(sleep_note) %></p>
     <p id="message" class="muted" hidden><%= field('message') %></p>
     <section class="error-panel setup-error" id="error-panel" role="alert" <%= 'hidden' unless @presentation['error'] %>>
       <h3>What went wrong</h3><pre id="error"><%= escape(@presentation['error']) %></pre>

data/lib/workspaces/dashboard_view.rb

@@ -215,6 +215,16 @@ module Workspaces
       [progress_step_text, progress['eta_text']].compact.join('. ')
     end
 
+    def sleep_note
+      sleep = @presentation['sleep']
+      return '' unless sleep
+      return 'Kept awake: this workspace will not sleep when idle.' if sleep['keep_awake']
+      return '' unless @presentation['state'] == 'ready'
+
+      minutes = (sleep['after_seconds'] / 60.0).round
+      "Sleeps after #{minutes >= 1 ? "#{minutes} min" : "#{sleep['after_seconds'].round} s"} without preview traffic."
+    end
+
     def preset_badge_text
       name = @presentation['current_preset']
       name ? "Preset: #{name}" : ''

data/lib/workspaces/front_door.rb

@@ -6,20 +6,31 @@ require_relative 'coordinator'
 require_relative 'dashboard_view'
 require_relative 'environment_overrides'
 require_relative 'proxy_middleware'
+require_relative 'activity_tracker'
+require_relative 'sleep_policy'
 
 module Workspaces
   class FrontDoor
     WORKSPACE_ROUTE = %r{\A/workspaces/([a-z0-9]+(?:-[a-z0-9]+)*)
-                          (?:/(status|start|prepare|restart|resume|stop|remove|update-pr|environment))?\z}x
+                          (?:/(status|start|prepare|restart|resume|stop|remove|update-pr|environment|keep-awake|allow-sleep))?\z}x
 
     # Rack env keys set on requests that reach a ready workspace backend, for use by
     # middleware registered with Workspaces.configure_proxy.
     WORKSPACE_ID_ENV = 'workspaces.workspace_id'.freeze
     WORKSPACE_ENV = 'workspaces.workspace'.freeze
 
-    def initialize(coordinator: Coordinator.new, registry: Registry.new)
+    WAKE_POLL_SECONDS = 0.25
+    RETRY_AFTER_SECONDS = 5
+    private_constant :WAKE_POLL_SECONDS, :RETRY_AFTER_SECONDS
+
+    attr_reader :tracker
+
+    def initialize(coordinator: Coordinator.new, registry: Registry.new, tracker: ActivityTracker.new,
+                   sleep_policy: SleepPolicy.new)
       @coordinator = coordinator
       @registry = registry
+      @tracker = tracker
+      @sleep_policy = sleep_policy
       @forwarder = ProxyMiddleware.build(method(:forward_to_backend))
     end
 
@@ -126,7 +137,9 @@ module Workspaces
       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)
+      when 'stop' then @coordinator.stop(id)
+      when 'keep-awake' then @coordinator.keep_awake(id, true)
+      when 'allow-sleep' then @coordinator.keep_awake(id, false)
       end
     end
 
@@ -147,13 +160,6 @@ module Workspaces
       response(422, e.message)
     end
 
-    def stop(id)
-      @registry.with_lock(id) do
-        Backend.new(id).stop!
-        StateStore.new(Config.state_file).set(id, 'status' => 'stopped', 'message' => 'Server stopped')
-      end
-    end
-
     def remove(request, id)
       unless request.media_type == 'application/x-www-form-urlencoded'
         return response(415, 'Deletion requires a form-encoded confirmation')
@@ -162,6 +168,7 @@ module Workspaces
       return response(422, 'Type the exact workspace ID to confirm deletion') unless request.POST['confirm_id'] == id
 
       @registry.remove(id, force: true)
+      @tracker.forget(id)
       redirect("#{Config.public_origin}/workspaces")
     rescue ArgumentError, Worktree::CommandFailedError, SystemCallError
       response(409, 'Workspace was not removed. Check the server logs and retry when safe.')
@@ -246,14 +253,106 @@ module Workspaces
     def proxy(id, request)
       return response(404, 'Unknown managed workspace') unless Worktree.new(id).exists?
 
+      counted = !@sleep_policy.ignored?(request.path_info)
+      lease = acquire_lease(id, counted)
+      return waking_unavailable(id) unless lease
+
+      begin
+        result = serve(id, request, counted)
+      rescue StandardError, Timeout::Error
+        lease.release
+        raise
+      end
+      hold_lease(result, lease)
+    rescue IOError, SystemCallError, Timeout::Error => e
+      response(502, "Workspace backend unavailable: #{e.class}")
+    end
+
+    def serve(id, request, counted)
+      phase = @coordinator.sleep_phase(id)
+      if phase
+        return sleeping_unavailable(id) unless counted
+
+        outcome = await_wake(id, phase)
+        return wake_failed(id) if outcome == :failed
+        return waking_unavailable(id) unless outcome == :ready
+      end
+
       snapshot = @coordinator.snapshot(id, include_log: false)
       return unavailable(id, request) unless snapshot['status'] == 'ready' && !snapshot['active']
 
       request.env[WORKSPACE_ID_ENV] = id
       request.env[WORKSPACE_ENV] = snapshot
       @forwarder.call(request.env)
-    rescue IOError, SystemCallError, Timeout::Error => e
-      response(502, "Workspace backend unavailable: #{e.class}")
+    end
+
+    # A lease keeps the workspace awake for as long as its request is being served. A response body
+    # that is still being produced (anything but a buffered Array) keeps it until the server closes it.
+    def hold_lease(result, lease)
+      status, headers, body = result
+      if body.is_a?(Array)
+        lease.release
+        return result
+      end
+
+      [status, headers, Rack::BodyProxy.new(body) { lease.release }]
+    end
+
+    # Requests are refused only while the workspace is being put to sleep, which takes a moment;
+    # they then wait their turn and wake it.
+    def acquire_lease(id, counted)
+      deadline = monotonic + Config.wake_timeout_seconds
+      loop do
+        lease = @tracker.acquire(id, counted: counted)
+        return lease if lease
+        return nil if monotonic >= deadline
+
+        sleep WAKE_POLL_SECONDS / 5
+      end
+    end
+
+    # Starts the wake (one request wins the workspace lock; the rest see it already running) and
+    # waits, within the wake timeout, for the server to be ready. :ready, :failed or :timeout.
+    def await_wake(id, phase)
+      @coordinator.wake(id) if phase == :sleeping
+      deadline = monotonic + Config.wake_timeout_seconds
+      loop do
+        outcome = wake_outcome(id)
+        return outcome if outcome
+        return :timeout if monotonic >= deadline
+
+        sleep WAKE_POLL_SECONDS
+      end
+    end
+
+    def wake_outcome(id)
+      return nil if @coordinator.sleep_phase(id)
+
+      case @coordinator.status_of(id)
+      when 'ready' then :ready
+      when 'preparing' then nil
+      else :failed
+      end
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def waking_unavailable(id)
+      retryable(503, "Workspace is waking up and not ready yet. Try again in a few seconds. Status: #{Config.dashboard_url(id)}")
+    end
+
+    def sleeping_unavailable(id)
+      retryable(503, "Workspace is asleep. Open it to wake it. Status: #{Config.dashboard_url(id)}")
+    end
+
+    def wake_failed(id)
+      retryable(503, "Workspace could not wake up. Details: #{Config.dashboard_url(id)}")
+    end
+
+    def retryable(status, message)
+      [status, headers('text/plain').merge('retry-after' => RETRY_AFTER_SECONDS.to_s), [message]]
     end
 
     def unavailable(id, request)

data/lib/workspaces/presentation.rb

@@ -3,11 +3,13 @@ require_relative 'progress'
 module Workspaces
   class Presentation
     TITLES = { 'idle' => 'Ready to start', 'stopped' => 'Server stopped', 'ready' => 'Workspace ready',
+               'sleeping' => 'Workspace asleep',
                'preparing' => 'Running setup', 'error' => 'Setup failed',
                'interrupted' => 'Setup interrupted' }.freeze
     ACTIONS = { 'start' => 'Start workspace', 'prepare' => 'Rebuild & restart',
                 'restart' => 'Restart server', 'stop' => 'Stop server',
-                'resume' => 'Retry failed step' }.freeze
+                'resume' => 'Retry failed step', 'keep-awake' => 'Keep awake',
+                'allow-sleep' => 'Allow sleep' }.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
@@ -55,6 +57,14 @@ module Workspaces
         environment_submit: 'Save & restart', environment_title: 'Change settings',
         open_environment: false, open_technical: false
       },
+      'sleeping' => {
+        sections: %w(lead environment) + TECHNICAL,
+        headline: 'Your workspace is asleep',
+        summary: 'It went quiet, so its server was stopped to free up resources. Your files and data are kept. ' \
+                 'Opening the preview wakes it in a few seconds.',
+        environment_submit: 'Save & start', environment_title: 'Change settings',
+        open_environment: false, open_technical: false
+      },
       'stopped' => {
         sections: %w(lead environment) + TECHNICAL,
         headline: 'Your workspace is paused',
@@ -95,7 +105,7 @@ module Workspaces
         'state' => state, 'sections' => sections,
         'headline' => definition[:headline], 'summary' => summary, 'resume' => resume,
         'lead_action' => lead_action, 'total' => total, 'progress' => progress,
-        'current_preset' => current_preset,
+        'current_preset' => current_preset, 'sleep' => sleep_info,
         'environment_title' => definition[:environment_title],
         'environment_submit' => definition[:environment_submit],
         'open' => { 'environment' => definition[:open_environment], 'technical' => definition[:open_technical] } }
@@ -107,6 +117,14 @@ module Workspaces
       @snapshot.fetch('status', 'idle')
     end
 
+    # What the page needs to explain sleeping: whether this workspace is kept awake, and after how
+    # long an idle one sleeps. Nil for states where sleeping is not in play.
+    def sleep_info
+      return nil unless %w(ready sleeping).include?(status) && !@snapshot['sleep_after_seconds'].nil?
+
+      { 'keep_awake' => !!@snapshot['keep_awake'], 'after_seconds' => @snapshot['sleep_after_seconds'] }
+    end
+
     def busy?
       @snapshot['active'] || status == 'preparing'
     end
@@ -133,6 +151,7 @@ module Workspaces
       case state
       when 'ready' then { 'kind' => 'open', 'label' => 'Open workspace' }
       when 'stopped' then { 'kind' => 'post', 'key' => 'start', 'label' => 'Start workspace' }
+      when 'sleeping' then { 'kind' => 'post', 'key' => 'start', 'label' => 'Wake workspace' }
       when 'error', 'interrupted' then (retryable? ? resume_action : retry_action).merge('kind' => 'post')
       end
     end
@@ -228,7 +247,9 @@ module Workspaces
     def actions
       return [] if busy?
       available = if status == 'ready'
-                    %w(prepare restart stop).map { |key| action(key, false) }
+                    %w(prepare restart stop).map { |key| action(key, false) } + keep_awake_actions
+                  elsif status == 'sleeping'
+                    [action('start', true).merge('label' => 'Wake workspace')] + keep_awake_actions
                   elsif retryable?
                     [resume_action, retry_action.merge('label' => 'Re-run all steps', 'primary' => false)]
                   elsif %w(error interrupted).include?(status)
@@ -241,6 +262,12 @@ module Workspaces
 
     end
 
+    def keep_awake_actions
+      return [] if @snapshot['sleep_after_seconds'].nil?
+
+      [action(@snapshot['keep_awake'] ? 'allow-sleep' : 'keep-awake', false)]
+    end
+
     def retry_action
       restart = @snapshot['operation'] == 'restart'
       action(restart ? 'restart' : 'prepare', true).merge('label' => restart ? 'Retry restart' : 'Retry setup')

data/lib/workspaces/recipe.rb

@@ -1,4 +1,6 @@
 require 'yaml'
+require 'json'
+require 'digest'
 require_relative 'config'
 require_relative 'environment_overrides'
 
@@ -9,7 +11,7 @@ module Workspaces
                       WORKSPACE_HOST WORKSPACE_CACHE_DIR WORKSPACE_RUN_ID).freeze
     LFS_STEP_ID = 'lfs'.freeze
     LFS_STEP_NAME = 'Fetch Git LFS files'.freeze
-    attr_reader :steps, :environment, :default_editable_env, :environment_presets, :lfs_fetch
+    attr_reader :steps, :environment, :default_editable_env, :environment_presets, :lfs_fetch, :sleep_ignore_paths
 
     def initialize(root: Config.repo_root)
       @root = root
@@ -19,6 +21,7 @@ module Workspaces
       @environment_presets = validate_environment_presets!(document.fetch('environment_presets', {}))
       @environment = validate_env!(document.fetch('env', {}))
       @lfs_fetch = validate_lfs!(document.fetch('lfs', {}))
+      @sleep_ignore_paths = validate_sleep!(document.fetch('sleep', {}))
       @steps = document.fetch('steps').map { |step| validate_step!(step) }
       @steps = [lfs_step] + @steps unless lfs_fetch.empty?
       validate_editable_overlap!
@@ -33,6 +36,14 @@ module Workspaces
       restart ? steps.drop(steps.index { |step| step['background'] }) : steps
     end
 
+    # Changes when a step that runs before the server changes. A sleeping workspace wakes by running
+    # only the server and readiness steps, unless this no longer matches what it was prepared with.
+    def preparation_digest
+      server = steps.index { |step| step['background'] }
+      material = { 'env' => environment, 'steps' => steps.first(server).map { |step| step.slice('id', 'run', 'env', 'timeout') } }
+      Digest::SHA256.hexdigest(JSON.generate(material))
+    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
@@ -61,7 +72,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 lfs steps))
+      unknown_keys!(document, %w(version env default_editable_env environment_presets lfs sleep steps))
       raise Invalid, 'steps must be a nonempty array' unless document['steps'].is_a?(Array) && !document['steps'].empty?
     end
 
@@ -131,6 +142,23 @@ module Workspaces
       paths.uniq
     end
 
+    # `sleep: { ignore_paths: [glob, ...] }` names preview paths that are background polling, so they
+    # do not keep an otherwise idle workspace awake. Globs match the request path (without the query).
+    def validate_sleep!(value)
+      raise Invalid, 'sleep must be a mapping' unless value.is_a?(Hash)
+
+      unknown_keys!(value, %w(ignore_paths))
+      paths = value.fetch('ignore_paths', [])
+      raise Invalid, 'sleep.ignore_paths must be an array of paths' unless paths.is_a?(Array)
+
+      paths.each do |path|
+        unless path.is_a?(String) && path.start_with?('/') && path == path.strip && !path.match?(/[[:cntrl:]]/)
+          raise Invalid, 'sleep.ignore_paths entries must be trimmed strings starting with /'
+        end
+      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/sleep_policy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+require_relative 'recipe'
+
+module Workspaces
+  # Which preview requests count as someone using a workspace. Health probes and the paths a recipe
+  # lists under `sleep.ignore_paths` are background traffic: they neither keep a workspace awake
+  # nor wake a sleeping one.
+  class SleepPolicy
+    DEFAULT_IGNORED_PATHS = %w(/health /up).freeze
+
+    def initialize(recipe_path: nil)
+      @recipe_path = recipe_path
+      @cached = nil
+    end
+
+    def ignored?(request_path)
+      globs.any? { |glob| File.fnmatch?(glob, request_path.to_s, File::FNM_EXTGLOB) }
+    end
+
+    private
+
+    def globs
+      path = @recipe_path || Config.repo_root.join('.workspaces.yml')
+      stamp = path.file? ? path.mtime : nil
+      return @cached[1] if @cached && @cached[0] == [path, stamp]
+
+      @cached = [[path, stamp], DEFAULT_IGNORED_PATHS + configured_globs(path)]
+      @cached[1]
+    end
+
+    def configured_globs(path)
+      Recipe.new(root: path.dirname).sleep_ignore_paths
+    rescue Recipe::Invalid
+      []
+    end
+  end
+end

data/lib/workspaces/sleeper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+
+module Workspaces
+  # Puts ready workspaces to sleep once they have seen no preview traffic for a while. It only
+  # decides when; stopping the server, and every check that must hold while it does, is the
+  # coordinator's. The tracker is what keeps a request that is being served from being cut off.
+  class Sleeper
+    def initialize(coordinator:, tracker:, threshold: Config.sleep_after_seconds, interval: Config.sleep_sweep_seconds)
+      @coordinator = coordinator
+      @tracker = tracker
+      @threshold = threshold
+      @interval = interval
+      @thread = nil
+    end
+
+    # Settles anything a previous front door left half done, then sweeps on a timer.
+    def start
+      return self if @threshold.nil?
+
+      @coordinator.reconcile_sleep
+      @thread = Thread.new do
+        loop do
+          sleep @interval
+          sweep
+        end
+      end
+      self
+    end
+
+    def stop
+      @thread&.kill
+      @thread = nil
+    end
+
+    def sweep
+      return [] if @threshold.nil?
+
+      @coordinator.sleep_candidates.select do |id|
+        @tracker.sleep_if_idle(id, @threshold) { @coordinator.sleep!(id) }
+      rescue StandardError => e
+        warn "[Workspaces] could not put #{id} to sleep: #{e.class}"
+        false
+      end
+    end
+  end
+end

data/lib/workspaces/version.rb

@@ -1,3 +1,3 @@
 module Workspaces
-  VERSION = '0.1.16'
+  VERSION = '0.1.17'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: workspaces
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.1.17
 platform: ruby
 authors:
 - Workspaces contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-22 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -70,6 +70,7 @@ files:
 - README.md
 - exe/workspaces
 - lib/workspaces.rb
+- lib/workspaces/activity_tracker.rb
 - lib/workspaces/backend.rb
 - lib/workspaces/build_history.rb
 - lib/workspaces/child_env.rb
@@ -95,6 +96,8 @@ files:
 - lib/workspaces/recipe.rb
 - lib/workspaces/registry.rb
 - lib/workspaces/resume_plan.rb
+- lib/workspaces/sleep_policy.rb
+- lib/workspaces/sleeper.rb
 - lib/workspaces/state_store.rb
 - lib/workspaces/step_log.rb
 - lib/workspaces/tee_log.rb