openclacky 1.5.21 → 1.5.22

data/lib/clacky/server/http_server.rb

@@ -75,26 +75,38 @@ module Clacky
         ev[:skill_command_display] = skill_command_display if skill_command_display
         ev[:editable] = false unless editable
         ev[:references] = references unless Array(references).empty?
-        rendered = Array(files).filter_map do |f|
+        rendered_images = []
+        rendered_attachments = []
+        Array(files).each do |f|
+          next if f[:reference] || f["reference"]
+
           url  = f[:data_url] || f["data_url"]
           name = f[:name]     || f["name"]
           path = f[:path]     || f["path"]
           type = f[:type]     || f["type"] || ""
+          mime = f[:mime_type] || f["mime_type"]
+          image = type.to_s == "image" || mime.to_s.start_with?("image/")
 
           if url
-            url
-          elsif type.to_s == "image" && path && File.exist?(path.to_s)
+            rendered_images << url
+          elsif image && path && File.exist?(path.to_s)
             # Serve via the /api/local-image proxy instead of inlining a base64
             # data URL. Inlining forced a synchronous disk-read + full base64
             # encode + downscale on every history replay (2-3s lag for sessions
             # with downgraded text-model images). The proxy lets the browser
             # lazy-load + cache the image, keeping the replay response tiny.
-            "/api/local-image?path=#{CGI.escape(path.to_s)}&v=#{File.mtime(path.to_s).to_i}"
+            rendered_images << "/api/local-image?path=#{CGI.escape(path.to_s)}&v=#{File.mtime(path.to_s).to_i}"
+          elsif image && name
+            rendered_images << "expired:#{name}"
           elsif name
-            type.to_s == "image" ? "expired:#{name}" : "pdf:#{name}"
+            attachment_type = type.to_s.empty? ? (mime || "file") : type
+            attachment = { name: name, type: attachment_type }
+            attachment[:path] = path if path && File.exist?(path.to_s)
+            rendered_attachments << attachment
           end
         end
-        ev[:images] = rendered unless rendered.empty?
+        ev[:images] = rendered_images unless rendered_images.empty?
+        ev[:attachments] = rendered_attachments unless rendered_attachments.empty?
         @events << ev
       end
 
@@ -838,9 +850,6 @@ module Clacky
             session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
             action     = path[%r{/git/([a-z]+)$}, 1]
             api_session_git(session_id, action, req, res)
-          elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/git/commit$})
-            session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
-            api_session_git_commit(session_id, req, res)
           elsif method == "POST" && path.match?(%r{^/api/sessions/[^/]+/git/restore$})
             session_id = path[%r{^/api/sessions/([^/]+)/git/}, 1]
             api_session_git_restore(session_id, req, res)
@@ -960,6 +969,12 @@ module Clacky
           elsif method == "DELETE" && path.match?(%r{^/api/memories/[^/]+$})
             filename = URI.decode_www_form_component(path.sub("/api/memories/", ""))
             api_memories_delete(filename, res)
+          elsif method == "GET" && path.match?(%r{^/api/projects/[^/]+/git$})
+            project_id = path.sub("/api/projects/", "").sub("/git", "")
+            api_project_git(project_id, req, res)
+          elsif method == "POST" && path.match?(%r{^/api/projects/[^/]+/git/checkout$})
+            project_id = path.sub("/api/projects/", "").sub("/git/checkout", "")
+            api_project_git_checkout(project_id, req, res)
           elsif method == "PATCH" && path.match?(%r{^/api/projects/[^/]+$})
             project_id = path.sub("/api/projects/", "")
             api_update_project(project_id, req, res)
@@ -2321,7 +2336,7 @@ module Clacky
         json_response(res, 200, {
           ok: true,
           provider: config["provider"],
-          key_masked: config["key"].empty? ? nil : mask_api_key(config["key"]),
+          keys_masked: masked_search_keys(config),
           available: Clacky::Utils::SearcherManager.available
         })
       end
@@ -2338,12 +2353,12 @@ module Clacky
           return json_response(res, 422, { error: "Unknown search provider: #{provider}" })
         end
 
-        key = body["key"].to_s
-        key = Clacky::SearchConfig.key if key.include?("****")
-
         current = Clacky::SearchConfig.load
         final_provider = body.key?("provider") ? provider : current["provider"]
-        final_key      = body.key?("key") ? key : current["key"]
+        # A masked value only ever stands for the same provider's stored key.
+        key = body["key"].to_s
+        key = Clacky::SearchConfig.key_for(final_provider) if key.include?("****")
+        final_key = body.key?("key") ? key : Clacky::SearchConfig.key_for(final_provider)
 
         # deepseek_web falls back to the configured model key, so it may be
         # saved without one. Every other searcher is a script that reads the
@@ -2361,11 +2376,15 @@ module Clacky
           key: body.key?("key") ? key : nil
         )
         config = Clacky::SearchConfig.load
-        json_response(res, 200, { ok: true, provider: config["provider"] })
+        json_response(res, 200, { ok: true, provider: config["provider"], keys_masked: masked_search_keys(config) })
       rescue => e
         json_response(res, 422, { error: e.message })
       end
 
+      private def masked_search_keys(config)
+        config["keys"].transform_values { |key| mask_api_key(key) }
+      end
+
       private def search_provider_known?(provider)
         return true if provider.empty?
         return true if provider == Clacky::SearchConfig::DEEPSEEK_WEB
@@ -2382,7 +2401,7 @@ module Clacky
         return json_response(res, 200, { ok: false, message: "provider is required" }) if provider.empty?
 
         key = body["key"].to_s
-        key = Clacky::SearchConfig.key if key.empty? || key.include?("****")
+        key = Clacky::SearchConfig.key_for(provider) if key.empty? || key.include?("****")
         return test_deepseek_web_search(res, key) if provider == Clacky::SearchConfig::DEEPSEEK_WEB
 
         script = Clacky::Utils::SearcherManager.path_for(provider)
@@ -4590,10 +4609,12 @@ module Clacky
 
         path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
         ext = File.extname(path).downcase.sub(/\A\./, "")
+        # Extension-less files (Dockerfile, Makefile, Gemfile) declare no
+        # document type, so no app lists them. Plain text is the closest
+        # approximation and keeps the picker useful.
+        ext = "txt" if ext.empty?
 
-        apps = if ext.empty?
-          []
-        elsif Utils::EnvironmentDetector.os_type == :wsl
+        apps = if Utils::EnvironmentDetector.os_type == :wsl
           Utils::WindowsAppDetector.apps_for_ext(ext)
         else
           Utils::MacAppDetector.apps_for_ext(ext)
@@ -4610,9 +4631,7 @@ module Clacky
         return json_response(res, 400, { error: "path is required" }) if raw_path.empty?
 
         path = Utils::EnvironmentDetector.resolve_local_path(raw_path)
-        app = if File.extname(path).empty?
-          nil
-        elsif Utils::EnvironmentDetector.os_type == :wsl
+        app = if Utils::EnvironmentDetector.os_type == :wsl
           Utils::WindowsAppDetector.default_app_for(path)
         else
           Utils::MacAppDetector.default_app_for(path)
@@ -4682,6 +4701,9 @@ module Clacky
         when "open"
           result = Utils::EnvironmentDetector.open_file(linux_path)
           return json_response(res, 501, { error: "unsupported OS" }) if result.nil?
+          # system() returns false when the launcher exits non-zero (broken app
+          # association, no handler). Surface it instead of a silent 200.
+          return json_response(res, 500, { error: "failed to open file" }) unless result
           json_response(res, 200, { ok: true })
         when "open_with"
           result = if Utils::EnvironmentDetector.os_type == :wsl
@@ -5414,9 +5436,22 @@ module Clacky
         when "status"
           json_response(res, 200, { repo: true }.merge(Clacky::Server::GitPanel.status(dir)))
         when "diff"
-          json_response(res, 200, { repo: true, diff: Clacky::Server::GitPanel.diff(dir, file: query["file"]) })
+          json_response(res, 200, { repo: true, diff: Clacky::Server::GitPanel.diff(
+            dir, file: query["file"], context: query["context"],
+            scope: query["scope"], base: query["base"]
+          ) })
+        when "review"
+          if query["scope"].to_s == "lastTurn"
+            json_response(res, 200, Clacky::Server::GitPanel.last_turn_review(git_session_agent(session_id)))
+          else
+            json_response(res, 200, Clacky::Server::GitPanel.review(
+              dir, scope: query["scope"], base: query["base"]
+            ))
+          end
         when "log"
-          json_response(res, 200, { repo: true, commits: Clacky::Server::GitPanel.log(dir, limit: query["limit"] || 50) })
+          json_response(res, 200, { repo: true, commits: Clacky::Server::GitPanel.log(
+            dir, limit: query["limit"] || 50, unpushed: query["unpushed"].to_s == "1"
+          ) })
         when "branches"
           json_response(res, 200, { repo: true, branches: Clacky::Server::GitPanel.branches(dir) })
         else
@@ -5424,24 +5459,6 @@ module Clacky
         end
       end
 
-      # POST /api/sessions/:id/git/commit — body: { message:, files: [..] }.
-      def api_session_git_commit(session_id, req, res)
-        dir = git_session_dir(session_id, res)
-        return unless dir
-
-        unless Clacky::Server::GitPanel.repo?(dir)
-          return json_response(res, 400, { error: "Not a git repository" })
-        end
-
-        body = parse_json_body(req)
-        result = Clacky::Server::GitPanel.commit(dir, message: body["message"], files: body["files"])
-        if result[:ok]
-          json_response(res, 200, result)
-        else
-          json_response(res, 422, { error: result[:error] })
-        end
-      end
-
       # POST /api/sessions/:id/git/restore - body: { file: }.
       # Discards uncommitted changes to one file, back to its HEAD state.
       def api_session_git_restore(session_id, req, res)
@@ -5545,8 +5562,7 @@ module Clacky
           json_response(res, 404, { error: "Session not found" })
           return nil
         end
-        session = @registry.get(session_id)
-        agent   = session && session[:agent]
+        agent = git_session_agent(session_id)
         unless agent
           json_response(res, 404, { error: "Session not found" })
           return nil
@@ -5558,6 +5574,11 @@ module Clacky
         end
         dir
       end
+
+      private def git_session_agent(session_id)
+        session = @registry.get(session_id)
+        session && session[:agent]
+      end
       # Lists one directory level inside the session's working_dir (lazy, per-layer).
       # Path traversal outside working_dir is rejected. Noisy dirs are hidden.
       IGNORED_FILE_ENTRIES = %w[.git .svn .hg node_modules .DS_Store .bundle vendor/bundle tmp .sass-cache].freeze
@@ -5571,7 +5592,11 @@ module Clacky
         return json_response(res, 404, { error: "Session not found" }) unless agent
 
         root = File.expand_path(agent.working_dir.to_s)
-        return json_response(res, 404, { error: "Working directory not found" }) unless Dir.exist?(root)
+        unless Dir.exist?(root)
+          # `code` lets the client tell "the folder was deleted" apart from any
+          # other failure and explain it, instead of showing a generic error.
+          return json_response(res, 404, { error: "Working directory not found", code: "working_dir_missing", path: root })
+        end
 
         query = URI.decode_www_form(req.query_string.to_s).to_h
         rel = query["path"].to_s
@@ -5596,7 +5621,9 @@ module Clacky
           end
         end
 
-        return json_response(res, 404, { error: "Directory not found" }) unless Dir.exist?(target)
+        unless Dir.exist?(target)
+          return json_response(res, 404, { error: "Directory not found", code: "directory_missing" })
+        end
         entries = Dir.children(target).reject do |name|
           IGNORED_FILE_ENTRIES.include?(name) || (!show_hidden && name.start_with?("."))
         end
@@ -7280,6 +7307,71 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      # GET /api/projects/:id/git?dir= — branch state of a work tree, used by
+      # the new-session branch picker. `dir` overrides the project's own
+      # working dir, since a session may run in a different repo. `repo: false`
+      # covers a missing working dir, a missing directory, and plain non-git
+      # folders, so the picker can simply hide itself.
+      def api_project_git(project_id, req, res)
+        project = @project_manager.find(project_id)
+        return json_response(res, 404, { error: "Project not found" }) unless project
+
+        dir = git_work_tree(project, git_dir_param(req))
+        return json_response(res, 200, { repo: false }) unless dir
+
+        json_response(res, 200, {
+          repo:     true,
+          branch:   Clacky::Server::GitPanel.branch_name(dir),
+          branches: Clacky::Server::GitPanel.branches(dir),
+        })
+      end
+
+      # POST /api/projects/:id/git/checkout — body: { branch:, create:?, from:?, dir:? }
+      # Switches a work tree. `create: true` branches off `from`, which may be
+      # a remote ref (origin/feature) to get a tracking branch.
+      def api_project_git_checkout(project_id, req, res)
+        project = @project_manager.find(project_id)
+        return json_response(res, 404, { error: "Project not found" }) unless project
+
+        body = parse_json_body(req)
+        dir  = git_work_tree(project, body["dir"])
+        return json_response(res, 400, { error: "Not a git repository" }) unless dir
+
+        result = Clacky::Server::GitPanel.checkout(
+          dir,
+          branch: body["branch"],
+          create: body["create"] == true,
+          from:   body["from"]
+        )
+
+        unless result[:ok]
+          return json_response(res, 422, { error: result[:error] })
+        end
+
+        json_response(res, 200, {
+          ok:       true,
+          branch:   Clacky::Server::GitPanel.branch_name(dir),
+          branches: Clacky::Server::GitPanel.branches(dir),
+        })
+      end
+
+      def git_dir_param(req)
+        URI.decode_www_form(req.query_string.to_s).to_h["dir"]
+      rescue ArgumentError
+        nil
+      end
+
+      # Resolves the work tree a git request targets: the explicit `dir` when
+      # given, otherwise the project's own working dir. Nil when the path is
+      # not an existing git repository.
+      def git_work_tree(project, dir_param)
+        raw = dir_param.to_s.strip
+        dir = raw.empty? ? project[:working_dir].to_s : File.expand_path(raw)
+        return nil if dir.empty? || !Dir.exist?(dir)
+        return nil unless Clacky::Server::GitPanel.repo?(dir)
+        dir
+      end
+
       # PATCH /api/projects/:id - update a project
       # Body: { name:?, description:?, color:?, working_dir:?, pinned:? } - only provided fields are changed
       def api_update_project(project_id, req, res)
@@ -8403,6 +8495,7 @@ module Clacky
           Thread.current[:task_epoch] = epoch
           run_result = task.call
           awaiting = false
+          web_ui = nil
           owns_epoch = true
           loop do
             owns_epoch = @registry.current_epoch(session_id).to_i == epoch.to_i
@@ -8412,6 +8505,7 @@ module Clacky
             @registry.with_session(session_id) do |s|
               owns_epoch = s[:epoch].to_i == epoch.to_i
               next unless owns_epoch
+              web_ui = s[:ui]
               awaiting = run_result.is_a?(Hash) && run_result[:awaiting_user_feedback]
               pending = agent.take_pending_input if Agent.task_completed?(run_result)
               unless pending
@@ -8430,7 +8524,11 @@ module Clacky
           # session history: a chime is a live cue, never replayed on refresh.
           # Also fires when awaiting feedback — that is precisely when the user
           # most needs pulling back; the flag lets the client word it differently.
-          broadcast_all(type: "task_finished", session_id: session_id, awaiting_feedback: !!awaiting)
+          finished = { type: "task_finished", session_id: session_id, awaiting_feedback: !!awaiting }
+          # Lets clients not viewing this session keep the summary until it is first opened.
+          complete = web_ui&.last_complete
+          finished[:complete] = complete if complete&.dig(:task_id) && run_result.is_a?(Hash) && complete[:task_id] == run_result[:task_id]
+          broadcast_all(finished)
           @session_manager.save(agent.to_session_data(status: :success, updated_at: Time.now))
           # Start idle compression timer now that the agent is idle
           idle_timer&.start

data/lib/clacky/server/preview.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "socket"
 require "timeout"
+require "uri"
 
 module Clacky
   module Server
@@ -47,18 +48,53 @@ module Clacky
         ".ogg"   => "audio/ogg"
       }.freeze
 
-      # Injected into preview HTML responses. The preview iframe is sandboxed
-      # without allow-same-origin, so the host page cannot read its location
-      # (and the iframe's src property does not follow internal navigations).
-      # Each served page therefore announces its own URL to the parent.
-      PREVIEW_NAV_REPORT = '<script>(function(){try{parent.postMessage({__clackyPreview:1,href:location.href},"*")}catch(e){}})()</script>'
+      # Injected into preview HTML responses. The preview iframe is cross-origin
+      # to the host page, so the host cannot read its location (and the iframe's
+      # src property does not follow internal navigations). Each served page
+      # therefore announces its own URL to the parent. Re-reporting is not just
+      # the initial load: Turbo/htmx/React-Router navigations swap the DOM
+      # without a full page load, so the same script also listens for their
+      # events, patches the History API and falls back to a slow poll.
+      PREVIEW_NAV_REPORT = <<~JS.freeze
+        <script>(function(){
+          var last = null;
+          function report(){
+            try {
+              if (location.href === last) return;
+              last = location.href;
+              parent.postMessage({__clackyPreview:1,href:location.href},"*");
+            } catch(e){}
+          }
+          report();
+          ["turbo:load","turbo:render","turbo:frame-load","htmx:afterSwap","pjax:end","DOMContentLoaded"].forEach(function(n){
+            document.addEventListener(n, report);
+          });
+          window.addEventListener("popstate", report);
+          window.addEventListener("hashchange", report);
+          var push = history.pushState, replace = history.replaceState;
+          history.pushState = function(){ push.apply(history, arguments); report(); };
+          history.replaceState = function(){ replace.apply(history, arguments); report(); };
+          setInterval(report, 500);
+        })()</script>
+      JS
+
+
+      # Must match ISOLATED_PREVIEW_HOST in
+      # default_extensions/preview/panels/preview/view.js. Chrome resolves
+      # every *.localhost name to loopback, so the preview frame runs on this
+      # origin while the UI stays on 127.0.0.1/localhost.
+      ISOLATED_PREVIEW_HOST = "preview.localhost"
+
+      # Hostnames a dev server may redirect to with an absolute URL. Only these
+      # are folded back into the proxy prefix; anything else is a deliberate
+      # off-box redirect and is passed through untouched.
+      LOOPBACK_HOSTS = %w[127.0.0.1 localhost ::1].freeze
 
       # Headers dropped when proxying a localhost dev server through the
-      # preview panel. X-Frame-Options is what blocks the sandboxed iframe;
-      # hop-by-hop headers and Set-Cookie must not cross the proxy boundary
-      # (WEBrick recomputes the former, cookies would leak the upstream's
-      # domain into ours). CSP frame-ancestors is handled separately so the
-      # rest of the policy survives.
+      # preview panel. X-Frame-Options is what blocks the sandboxed iframe and
+      # hop-by-hop headers are recomputed by WEBrick. Set-Cookie is handled
+      # separately (see #preview_cookie) because the isolated preview origin
+      # needs the upstream session to survive inside a third-party frame.
       PROXY_SKIP_HEADERS = %w[
         x-frame-options
         transfer-encoding
@@ -70,7 +106,6 @@ module Clacky
         te
         trailer
         upgrade
-        set-cookie
       ].freeze
 
       # Connection-stage failures when dialing the localhost dev server. The
@@ -189,11 +224,8 @@ module Clacky
       # the document start) so the reporter runs before page scripts while a
       # leading <!DOCTYPE> stays first — prepending would flip the document
       # into quirks mode.
-      private def preview_body(abs)
-        body = File.binread(abs)
-        return body unless (PREVIEW_CONTENT_TYPES[File.extname(abs).downcase] || "").start_with?("text/html")
-
-        html = body.force_encoding(Encoding::UTF_8)
+      private def inject_nav_report(html)
+        html = html.force_encoding(Encoding::UTF_8)
         if (m = html.match(/<head[^>]*>/i))
           html[m.end(0), 0] = PREVIEW_NAV_REPORT
         elsif (m = html.match(/<html[^>]*>/i))
@@ -206,6 +238,13 @@ module Clacky
         html
       end
 
+      private def preview_body(abs)
+        body = File.binread(abs)
+        return body unless (PREVIEW_CONTENT_TYPES[File.extname(abs).downcase] || "").start_with?("text/html")
+
+        inject_nav_report(body)
+      end
+
       # Decode %XX escapes in a preview path segment without treating "+" as
       # space: "+" is a legal literal character in file names.
       private def preview_decode_path(seg)
@@ -285,6 +324,15 @@ module Clacky
             next if value.nil? || value.empty?
           end
           next if PROXY_SKIP_HEADERS.include?(down)
+          if down == "set-cookie"
+            cookie = preview_cookie(value)
+            res.cookies << cookie if cookie && isolated_preview_request?(req)
+            next
+          end
+          if down == "location"
+            res[name] = rewrite_preview_location(value, port, req)
+            next
+          end
           if down == "content-type"
             is_html = value.start_with?("text/html")
             is_css  = value.start_with?("text/css")
@@ -300,7 +348,7 @@ module Clacky
         if req.request_method != "HEAD"
           body = resp.body.to_s
           if is_html
-            body = rewrite_preview_paths(body, port)
+            body = inject_nav_report(rewrite_preview_paths(body, port))
           elsif is_css
             body = rewrite_preview_css(body, port)
           end
@@ -319,6 +367,59 @@ module Clacky
         stripped.empty? ? nil : stripped
       end
 
+      # Rewrites an upstream Set-Cookie so it survives inside the preview
+      # frame. The frame is a third-party context for the host UI, where Chrome
+      # drops SameSite=Lax/Strict cookies outright, so the session cookie the
+      # dev server just set would be discarded and every page would look like a
+      # fresh, cookie-less visit. SameSite=None needs Secure, which Chrome
+      # accepts over http for *.localhost because it is a trustworthy origin.
+      # Domain is dropped so the cookie stays pinned to the preview origin and
+      # can never be read by the host UI.
+      private def preview_cookie(value)
+        parts = value.to_s.split(";").map(&:strip).reject(&:empty?)
+        return nil if parts.empty?
+
+        kept = parts[1..-1].reject do |attr|
+          attr =~ /\A(?:domain|samesite)\s*=/i || attr =~ /\Asecure\z/i
+        end
+        ([parts.first] + kept + ["SameSite=None", "Secure"]).join("; ")
+      end
+
+      private def isolated_preview_request?(req)
+        req["Host"].to_s.split(":").first.to_s.downcase == ISOLATED_PREVIEW_HOST
+      end
+
+      # An upstream 3xx points at the dev server root (/dashboard). Inside the
+      # isolated preview frame that resolves against the proxy origin and loses
+      # the /preview/p/<port> prefix, so the redirect lands on a 404 — and the
+      # address bar never sees the new page. Keep root-relative redirects inside
+      # the prefix and fold absolute ones that point back at the same dev
+      # server. Off-box and already-prefixed URLs pass through untouched.
+      private def rewrite_preview_location(value, port, req)
+        return value unless isolated_preview_request?(req)
+
+        prefix = "/preview/p/#{port}"
+        if value.start_with?("/") && !value.start_with?("//")
+          return value if value == prefix || value.start_with?("#{prefix}/", "#{prefix}?")
+
+          return "#{prefix}#{value}"
+        end
+
+        uri = begin
+          URI.parse(value)
+        rescue URI::InvalidURIError
+          return value
+        end
+        return value unless uri.host
+        return value unless LOOPBACK_HOSTS.include?(uri.host.downcase)
+        return value unless uri.port == port
+
+        path = uri.path.to_s.empty? ? "/" : uri.path
+        path += "?#{uri.query}" if uri.query
+        path += "##{uri.fragment}" if uri.fragment
+        "#{prefix}#{path}"
+      end
+
       # Rewrites absolute-path resource URLs (/assets/app.js) in a proxied HTML
       # page to the proxy prefix so the browser resolves them against the dev
       # server instead of the host origin. Protocol-relative (//), already

data/lib/clacky/server/scheduler.rb

@@ -141,13 +141,15 @@ module Clacky
         list_tasks.map do |task_name|
           content  = begin; read_task(task_name); rescue StandardError; ""; end
           schedule = schedule_map[task_name] || {}
+          cron     = schedule["cron"]
           {
             "name"    => task_name,
             "content" => content,
-            "cron"    => schedule["cron"],
+            "cron"    => cron,
             "enabled" => schedule.fetch("enabled", true),
             "scheduled" => !schedule.empty?,
-            "last_run" => last_runs[task_name]
+            "last_run" => last_runs[task_name],
+            "next_run" => cron ? cron_next_run(cron) : nil
           }
         end
       end
@@ -383,6 +385,83 @@ module Clacky
 
       # ── Cron parsing ─────────────────────────────────────────────────────────
 
+      # First time the 5-field cron expression fires strictly after +from+.
+      # Walks day by day (two years max) and only expands the hour/minute grid
+      # for days that match, so a yearly task costs ~365 cheap comparisons.
+      # Returns nil for malformed expressions and impossible ones (Feb 30).
+      private def cron_next_run(expr, from: Time.now)
+        fields = expr.to_s.strip.split(/\s+/)
+        return nil unless fields.size == 5
+
+        sets = [
+          cron_field_values(fields[0], 0, 59),
+          cron_field_values(fields[1], 0, 23),
+          cron_field_values(fields[2], 1, 31),
+          cron_field_values(fields[3], 1, 12),
+          cron_field_values(fields[4], 0, 6)
+        ]
+        return nil if sets.any?(&:nil?)
+
+        minutes, hours, doms, months, dows = sets
+        return nil if minutes.empty? || hours.empty? || doms.empty? || months.empty? || dows.empty?
+
+        # Anchor at noon so a day-step never lands on the wrong date across a
+        # DST boundary (Time#+ is absolute seconds, not calendar days).
+        noon  = Time.local(from.year, from.month, from.day, 12)
+        # Minute-of-day of the first candidate; same-day scans start here.
+        floor = from.hour * 60 + from.min + 1
+
+        (0..731).each do |offset|
+          day = noon + offset * 86_400
+          next unless months.include?(day.month) && doms.include?(day.day) && dows.include?(day.wday)
+
+          limit = offset.zero? ? floor : 0
+          hours.each do |h|
+            next if h * 60 + minutes.last < limit
+
+            minutes.each do |m|
+              next if h * 60 + m < limit
+
+              return Time.local(day.year, day.month, day.day, h, m, 0)
+            end
+          end
+        end
+
+        nil
+      end
+
+      # Concrete values a single cron field can take, mirroring the semantics of
+      # #cron_part_matches?. Returns nil when the field is unparseable.
+      private def cron_field_values(field, min, max)
+        values = []
+        field.to_s.split(",").each do |part|
+          part      = part.strip
+          base, step = part.split("/")
+          step      = step ? step.to_i : 1
+          return nil if step <= 0
+
+          lo, hi = if base == "*"
+                     [min, max]
+                   elsif base.include?("-")
+                     base.split("-").map(&:to_i)
+                   else
+                     value = Integer(base, exception: false)
+                     return nil if value.nil?
+                     [value, value]
+                   end
+          return nil if lo.nil? || hi.nil? || hi < lo
+
+          (lo..hi).each do |v|
+            next unless v.between?(min, max)
+            # `*` steps from zero (matches value % step), ranges step from lo.
+            next unless base == "*" ? (v % step).zero? : ((v - lo) % step).zero?
+
+            values << v
+          end
+        end
+        values.uniq.sort
+      end
+
       # Returns true if the 5-field cron expression matches the given Time.
       # Fields: minute hour day-of-month month day-of-week
       private def cron_matches?(expr, time)