samagotchi 0.158.0 → 0.160.0

data/lib/samagotchi/project_id_clash.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "atomic_file"
+require_relative "memory_paths"
+require_relative "paths"
+
+module Samagotchi
+  # Two folders with one chi project id: a marked folder copied (cp -R)
+  # keeps its marker, so the copy shares the original's memories. Told at
+  # session start (Engine#announce_load_events!, label "memory", beside
+  # MemoryOrphans), at every session start while it lasts.
+  #
+  # The claim: an id-keyed memories folder's `.root` names the folder that
+  # last started a session with it (one line; a dotfile, so no *.md glob
+  # lists it). Written only here, at session start, never by the key
+  # resolver: a read-only command or a memory call must not write.
+  ProjectIdClash = Data.define(:root, :other, :id) do
+    # The one text for the condition.
+    def message
+      "#{Paths.tilde(root)} and #{Paths.tilde(other)} share chi project id #{id} (a copied folder?): they share " \
+        "memories; `chi project init --new-id` gives this one its own."
+    end
+  end
+
+  class ProjectIdClash
+    CLAIM = ".root"
+
+    # +cwd+'s project, when a marked one with an id: a clash when the claim
+    # names another folder that still has a marker with this id; otherwise
+    # the claim is set to this root (when it changes; a moved folder just
+    # takes it over). Only once the id folder exists: nothing is made for a
+    # project with no memories yet.
+    # @return [ProjectIdClash, nil]
+    def self.check(env: ENV, cwd: Dir.pwd, home: MemoryPaths.default_home)
+      found = MemoryPaths.lookup(cwd, home: home)
+      return nil unless found.id
+
+      dir = File.join(MemoryPaths.projects_dir(env: env), found.id)
+      return nil unless File.directory?(dir)
+
+      claim = File.join(dir, CLAIM)
+      other = File.file?(claim) ? File.read(claim, 4096).to_s.lines.first.to_s.strip : ""
+      return nil if other == found.root
+      return new(root: found.root, other: other, id: found.id) if same_project?(other, found.id, home)
+
+      AtomicFile.write(claim, "#{found.root}\n")
+      nil
+    rescue SystemCallError
+      nil
+    end
+
+    # Whether +other+ still is a marked folder with +id+ (not gone, not
+    # given another id).
+    def self.same_project?(other, id, home)
+      return false if other.empty? || !File.directory?(other)
+
+      found = MemoryPaths.lookup(other, home: home)
+      found.marker? && found.root == File.realpath(other) && found.id == id
+    end
+    private_class_method :same_project?
+  end
+end

data/lib/samagotchi/project_init.rb

@@ -1,20 +1,43 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require_relative "atomic_file"
+require_relative "context_sources"
 require_relative "guardrails/path_resolve"
+require_relative "memory_orphans"
 require_relative "memory_paths"
 require_relative "paths"
+require_relative "project_id"
+require_relative "session_paths"
 
 module Samagotchi
-  # The shared decisions for `chi project init` and chi web's project picker.
+  # The shared decisions for `chi project init` and chi web's project picker,
+  # and every text they refuse or report with (the CLI prints them). A new
+  # marker gets an id (ProjectId); #adopt gives an older marker one, #new_id
+  # a copied folder its own.
   module ProjectInit
-    Outcome = Data.define(:kind, :reason, :root, :top, :nested_in, :message)
+    # +id+: the project's id (ProjectId), nil for none (a git repository, a
+    # marker without one, a refusal).
+    Outcome = Data.define(:kind, :reason, :root, :top, :nested_in, :message, :id) do
+      def initialize(kind:, reason:, root:, top:, nested_in:, message:, id: nil) = super
+    end
+
+    # A folder keyed by the project key (MemoryPaths.key_for): under +base+,
+    # named +prefix+ + the key.
+    Place = Data.define(:base, :prefix) do
+      def path(key) = File.join(base, "#{prefix}#{key}")
+    end
 
     MARKER_TEXT = "# chi project marker: this folder is a chi project (docs/memory.md)\n"
 
     module_function
 
-    def call(dir, home:)
+    # Marks +dir+ (a new marker gets an id), or says why not. A folder whose
+    # path key already names a folder (memories kept while it was no
+    # project, keyed by the same path) is marked without an id, so nothing
+    # it has goes out of reach: #adopt moves those and writes the id.
+    # @param state_dir [String, nil] the sessions dir (SessionPaths.default_state_dir)
+    def call(dir, home:, env: ENV, state_dir: nil)
       dir = File.expand_path(dir.to_s)
       found = MemoryPaths.lookup(dir, home: home)
       if found.git?
@@ -32,19 +55,94 @@ module Samagotchi
       # The marked project this folder sits in, if any: the folder itself (already marked) or its parent project.
       enclosing = found.marker? ? found.root : nil
       if enclosing == Guardrails::PathResolve.real(dir)
+        id_part = found.id ? " (id #{found.id})" : ""
         return Outcome.new(kind: :already_marked, reason: nil, root: enclosing, top: found.top, nested_in: nil,
-                           message: "#{Paths.tilde(enclosing)} is already a chi project")
+                           message: "#{Paths.tilde(enclosing)} is already a chi project#{id_part}", id: found.id)
       end
 
-      write_marker(dir)
+      id = write_marker(dir, places(env: env, state_dir: state_dir || SessionPaths.default_state_dir(env: env)))
       root = File.realpath(dir)
       # No message: each surface words its own success (the CLI's report, the web's navigation).
-      Outcome.new(kind: :created, reason: nil, root: root, top: root, nested_in: enclosing, message: nil)
+      Outcome.new(kind: :created, reason: nil, root: root, top: root, nested_in: enclosing, message: nil, id: id)
     rescue SystemCallError => e
       marker = File.join(dir, MemoryPaths::MARKER)
       write_failed("couldn't write #{Paths.tilde(marker)}: #{e.message}")
     end
 
+    # `chi project init` (the CLI only: chi web's New-project row calls
+    # #call, which never moves folders): #call, and for a marked folder
+    # with no valid id, its adoption of one. The folders keyed by its path
+    # key (its memories, its project context sources, the skills bundle's
+    # kept versions) move to the id, each leaving a link by its old name so
+    # an older chi, keying by path, finds the same folder; then the id is
+    # written (a crash before that leaves the path key reaching the moved
+    # folders through the links, and a rerun finishes with the same id).
+    # Refused while a running session belongs to the project: its worker
+    # could write a memory under the old name between a move and its link.
+    # @param state_dir [String, nil] the sessions dir (SessionPaths.default_state_dir)
+    # @param sessions [Array<SessionRow>] this machine's sessions (+live+, +project+, +id+)
+    # A folder #call marked without an id is adopted the same way.
+    # @param sessions [Array<SessionRow>] this machine's sessions (+live+,
+    #   +project+, +cwd+, +id+): a running one in the project (by the root it
+    #   stored, else its folder's) refuses
+    # @return [Outcome] :adopted (its message the report), :created (its
+    #   message what moved, nil when nothing did) or #call's
+    def adopt(dir, home:, env: ENV, state_dir: nil, sessions: [])
+      state_dir ||= SessionPaths.default_state_dir(env: env)
+      outcome = call(dir, home: home, env: env, state_dir: state_dir)
+      return outcome unless %i[already_marked created].include?(outcome.kind) && outcome.id.nil?
+
+      root = outcome.root
+      running = Array(sessions).select do |row|
+        row.live && (row.project ? row.project == root : MemoryPaths.lookup(row.cwd.to_s, home: home).root == root)
+      end
+      unless running.empty?
+        return refused(:running, root, "#{Paths.tilde(root)} has running sessions " \
+                                       "(#{running.map { |row| row.id[0, 8] }.join(", ")}): stop them " \
+                                       "(chi sessions stop ID) and rerun chi project init, which moves the " \
+                                       "project's folders while no session can write to them")
+      end
+
+      adopted = adopt_id(root, env: env, state_dir: state_dir)
+      return adopted unless outcome.kind == :created && adopted.kind == :adopted
+
+      # A new project: the CLI words its success; the report keeps what moved.
+      moved = adopted.message.lines.drop(1).join.chomp
+      outcome.with(id: adopted.id, message: moved.empty? ? nil : moved)
+    rescue SystemCallError => e
+      write_failed("couldn't adopt an id for #{Paths.tilde(outcome&.root || dir.to_s)}: #{e.message}")
+    end
+
+    # `chi project init --new-id`: a fresh id for a marked folder (a copied
+    # one, going its own way), its folders copied from the key it had to the
+    # new id (the copy keeps what it had; the other folder keeps its own).
+    # @return [Outcome] :new_id (its message the report) or :refused
+    def new_id(dir, home:, env: ENV, state_dir: nil)
+      dir = File.expand_path(dir.to_s)
+      found = MemoryPaths.lookup(dir, home: home)
+      unless found.marker? && found.root == Guardrails::PathResolve.real(dir)
+        return refused(:not_marked, nil, "#{Paths.tilde(dir)} is not a marked chi project folder: --new-id gives " \
+                                         "one (made with chi project init) an id of its own")
+      end
+
+      root = found.root
+      old_key = MemoryPaths.key_for(root: root, id: found.id)
+      id = ProjectId.generate(File.basename(root))
+      lines = ["#{Paths.tilde(root)} has a chi project id of its own now: #{id} (was #{found.id || "none: keyed by its path"})"]
+      places(env: env, state_dir: state_dir || SessionPaths.default_state_dir(env: env)).each do |place|
+        from = place.path(old_key)
+        next unless File.directory?(from)
+
+        to = place.path(id)
+        copy_folder(File.realpath(from), to)
+        lines << "copied #{Paths.tilde(from)} to #{Paths.tilde(to)}"
+      end
+      write_id(root, id)
+      Outcome.new(kind: :new_id, reason: nil, root: root, top: root, nested_in: nil, message: lines.join("\n"), id: id)
+    rescue SystemCallError => e
+      write_failed("couldn't give #{Paths.tilde(dir)} a new id: #{e.message}")
+    end
+
     # chi web opens a folder in a git repository without marking it, so the folder has to exist.
     # @return [Outcome, nil] a refused (:write_failed) outcome when it can't be made, else nil
     def ensure_folder(dir)
@@ -54,16 +152,122 @@ module Samagotchi
       write_failed("couldn't create #{Paths.tilde(dir)}: #{e.message}")
     end
 
+    # The folders a project key names: its memories, its project context
+    # sources (where the workers keep them: ContextSources.root), and the
+    # skills bundle's kept versions of its project skills (history/
+    # project-<key>, the bundle's own data dir).
+    # @return [Array<Place>]
+    def places(env:, state_dir:)
+      [Place.new(base: MemoryPaths.projects_dir(env: env), prefix: ""),
+       Place.new(base: File.join(ContextSources.root(state_dir: state_dir), "projects"), prefix: ""),
+       Place.new(base: File.join(File.dirname(state_dir), "plugins", "skills", "history"), prefix: "project-")]
+    end
+
+    def adopt_id(root, env:, state_dir:)
+      problem = ProjectId.read(root).problem
+      path_key = MemoryPaths.key_for_root(root)
+      # Before the id: what MemoryOrphans finds for the project keyed by its path.
+      orphans = MemoryOrphans.find(env: env, cwd: root)
+      list = places(env: env, state_dir: state_dir)
+      id = resumed_id(list.first, path_key) || ProjectId.generate(File.basename(root))
+      taken = list.map { |place| [place.path(path_key), place.path(id)] }
+                  .find { |from, to| real_dir?(from) && (File.exist?(to) || File.symlink?(to)) }
+      if taken
+        return refused(:id_taken, root, "#{Paths.tilde(taken[1])} already exists: chi project init can't move " \
+                                        "#{Paths.tilde(taken[0])} there; nothing moved")
+      end
+
+      lines = ["#{Paths.tilde(root)} now has the chi project id #{id}: its memories and project context stay " \
+               "with it when the folder moves or is renamed"]
+      lines << "#{problem}: replaced" if problem
+      list.each { |place| lines.concat(move_folder(place.path(path_key), place.path(id))) }
+      write_id(root, id)
+      if orphans
+        lines << "memories from an earlier path: #{orphans.candidates.map { |c| Paths.tilde(c) }.join(", ")} (this " \
+                 "folder's name with another path's hash; if they are this project's, move their files into " \
+                 "#{Paths.tilde(list.first.path(id))})"
+      end
+      Outcome.new(kind: :adopted, reason: nil, root: root, top: root, nested_in: nil, message: lines.join("\n"), id: id)
+    end
+
+    # The id an adoption that crashed before writing it chose: the path
+    # key already a link to an id folder beside it.
+    def resumed_id(place, path_key)
+      link = place.path(path_key)
+      return nil unless File.symlink?(link)
+
+      target = File.readlink(link)
+      target if target.match?(ProjectId::PATTERN) && File.directory?(place.path(target))
+    end
+
+    def real_dir?(path) = File.directory?(path) && !File.symlink?(path)
+
+    # Move +from+ to +to+ and leave a link named +from+ (relative: the
+    # folder may move with its parent). Nothing to move (no folder, or a
+    # link already): no move and no link. A folder made again at +from+
+    # between the move and the link has its files moved over (none
+    # replaced), then gives way to the link; what was in both stays.
+    # @return [Array<String>] the report's lines
+    def move_folder(from, to)
+      return [] unless real_dir?(from)
+
+      File.rename(from, to)
+      begin
+        File.symlink(File.basename(to), from)
+      rescue Errno::EEXIST
+        Dir.children(from).each do |name|
+          File.rename(File.join(from, name), File.join(to, name)) unless File.exist?(File.join(to, name))
+        end
+        unless Dir.empty?(from)
+          return ["moved #{Paths.tilde(from)} to #{Paths.tilde(to)}; files written to the old folder meanwhile " \
+                  "that #{Paths.tilde(to)} has too stay in #{Paths.tilde(from)}"]
+        end
+
+        Dir.rmdir(from)
+        File.symlink(File.basename(to), from)
+      end
+      ["moved #{Paths.tilde(from)} to #{Paths.tilde(to)} (the old name links to it, for an older chi)"]
+    end
+
+    # +to+ made a copy of +from+'s files, without the copied project's
+    # claim (.root: ProjectIdClash).
+    def copy_folder(from, to)
+      FileUtils.mkdir_p(to)
+      FileUtils.cp_r(File.join(from, "."), to)
+      FileUtils.rm_f(File.join(to, ".root"))
+    end
+
+    def write_id(root, id)
+      marker = File.join(root, MemoryPaths::MARKER)
+      AtomicFile.write(marker, ProjectId.with_id(File.read(marker), id))
+    end
+
+    def refused(reason, root, message)
+      Outcome.new(kind: :refused, reason: reason, root: root, top: root, nested_in: nil, message: message)
+    end
+
     def write_failed(message)
       Outcome.new(kind: :refused, reason: :write_failed, root: nil, top: nil, nested_in: nil, message: message)
     end
-    private_class_method :write_failed
 
-    def write_marker(dir)
+    # @param places [Array<Place>] the folders a key names (#places)
+    # @return [String, nil] the new marker's id; nil when a folder already
+    #   has the path key (#call)
+    def write_marker(dir, places)
       marker = File.join(dir, MemoryPaths::MARKER)
       FileUtils.mkdir_p(File.dirname(marker))
-      File.write(marker, MARKER_TEXT)
+      root = File.realpath(dir)
+      key = MemoryPaths.key_for_root(root)
+      if places.any? { |place| File.exist?(place.path(key)) || File.symlink?(place.path(key)) }
+        File.write(marker, MARKER_TEXT)
+        return nil
+      end
+
+      id = ProjectId.generate(File.basename(root))
+      File.write(marker, ProjectId.with_id(MARKER_TEXT, id))
+      id
     end
-    private_class_method :write_marker
+    private_class_method :write_failed, :write_marker, :refused, :adopt_id, :resumed_id, :real_dir?, :move_folder,
+                         :copy_folder, :write_id
   end
 end

data/lib/samagotchi/project_scope.rb

@@ -18,10 +18,19 @@ module Samagotchi
       return nil if dir.empty?
       return cache[dir] if cache&.key?(dir)
 
-      found = MemoryPaths.lookup(File.expand_path(dir))
-      root = found.project? ? found.root : nil
+      root = project_for(dir)&.root
       cache[dir] = root if cache
       root
     end
+
+    # +dir+'s project (MemoryPaths::ProjectLookup: its root and, for a
+    # marked project, its id), or nil in none.
+    def project_for(dir)
+      dir = dir.to_s
+      return nil if dir.empty?
+
+      found = MemoryPaths.lookup(File.expand_path(dir))
+      found.project? ? found : nil
+    end
   end
 end

data/lib/samagotchi/run_options.rb

@@ -214,6 +214,7 @@ module Samagotchi
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi home [set [--ruby PATH] | doctor]   the Ruby every chi launch boots
                  chi project [init [DIR]]         this folder's project; init makes a folder in no git repository one
+                 chi schedule <add|list|show|tick|run-now|enable|disable|cancel>   durable schedules that outlive every worker
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME
                  chi --remote NAME <send|answer|note|context|sessions|share|review> …   those commands on that machine (or CHI_REMOTE=NAME)
                  chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]   a session on that machine, in this terminal

data/lib/samagotchi/schedule_command.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "schedules"
+require_relative "session"
+
+module Samagotchi
+  # `chi schedule`: durable schedules that outlive every worker (docs/scheduling.md).
+  # A tick run by cron, systemd or chi web's hub (`chi schedule tick`) fires the
+  # entries whose time has come against a session: the next link of its chain
+  # (the default), or a queued turn in the session itself.
+  # bin/chi dispatches here before OptionParser; this machine only.
+  class ScheduleCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi schedule <add|list|show|tick|run-now|enable|disable|cancel> [flags]
+
+        add --session ID (--continues ID) (-m|--message|--prompt TEXT) [--title TEXT]
+            one of: --every 30m | --weekday 1 --time 09:00 | --date 2026-11-20T09:00
+            [--mode chain|same] [--catch-up once|none] [--keep-links N] [--max-failures N] [--max-skips N]
+        list [--all] [--format text|json]
+        show ID
+        tick [--dry-run] [--format text|json]
+        run-now ID
+        enable ID | disable ID | cancel ID
+
+      Recurrence: --every 45m / 2h / 1d (UTC interval math: an `every 1d` schedule drifts
+      an hour across a DST change — use --weekday for a wall-clock time);
+      --weekday 1..7 (1=Mon) with --time HH:MM in the machine's local zone;
+      --date one local moment.
+      Modes: chain (default) runs the prompt as the next link of the session's chain;
+      same queues it as a turn in the session itself.
+      A busy target is skipped and retried at the next tick; after max_skips skips
+      (default 12) or max_failures failures (default 3) the schedule is disabled.
+    TEXT
+
+    SUBCOMMANDS = %w[add list show tick run-now enable disable cancel].freeze
+
+    # A usage error names the subcommand it was given (CLI::Command's
+    # usage_error builds its line from this).
+    def command_name = SUBCOMMANDS.include?(@argv.first.to_s) ? "chi schedule #{@argv.first}" : "chi schedule"
+
+    FLAGS = {
+      "add" => CLI::Flags.new(args: true) do |f|
+        f.value "--session", "--continues", key: :target
+        f.value "-m", "--message", "--prompt", key: :prompt
+        f.value "--title"
+        f.value "--every"
+        f.value "--weekday"
+        f.value "--time"
+        f.value "--date"
+        f.value "--mode"
+        f.value "--catch-up"
+        f.value "--keep-links"
+        f.value "--max-failures"
+        f.value "--max-skips"
+      end,
+      "list" => CLI::Flags.new(args: false) do |f|
+        f.switch "--all", key: :include_disabled
+        f.value "--format"
+      end,
+      "show" => CLI::Flags.new(args: true),
+      "tick" => CLI::Flags.new(args: false) do |f|
+        f.switch "--dry-run"
+        f.value "--format"
+      end,
+      "run-now" => CLI::Flags.new(args: true),
+      "enable" => CLI::Flags.new(args: true),
+      "disable" => CLI::Flags.new(args: true),
+      "cancel" => CLI::Flags.new(args: true)
+    }.freeze
+
+    # @param argv [Array<String>] the arguments after "schedule"
+    # @param schedules [Schedules, nil] the store; default this machine's
+    def initialize(argv, stdout: $stdout, stderr: $stderr, schedules: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @schedules = schedules || Schedules.new
+    end
+
+    # @return [Integer] exit status: 0 ok, 1 a missing session or schedule,
+    #   2 a usage error
+    def run
+      sub = @argv[0]
+      if sub.nil? || HELP_WORDS.include?(sub)
+        @stdout.puts(USAGE)
+        return 0
+      end
+      return usage_error("unknown subcommand #{sub}") unless SUBCOMMANDS.include?(sub)
+
+      parsed = parse_flags(FLAGS.fetch(sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      @opts = parsed.options
+      @args = parsed.args
+
+      case sub
+      when "add" then add
+      when "list" then list
+      when "show" then show
+      when "tick" then tick
+      when "run-now" then act { |id| @schedules.run_now(id) }
+      when "enable" then act { |id| @schedules.enable(id) }
+      when "disable" then act { |id| @schedules.disable(id) }
+      when "cancel" then act { |id| @schedules.cancel(id) }
+      end
+    end
+
+    private
+
+    def add
+      if @opts[:target].to_s.strip.empty? && !@args.empty?
+        return usage_error("add takes the session with --session ID, not #{@args.map { |arg| arg.inspect }.join(" ")}")
+      end
+      return usage_error("add needs --session ID (the session the schedule runs against)") if @opts[:target].to_s.strip.empty?
+      return usage_error("add needs a prompt: -m \"...\"") if @opts[:prompt].to_s.strip.empty?
+
+      begin
+        recurrence = Schedules.recurrence(every: @opts[:every], weekday: @opts[:weekday], time: @opts[:time], date: @opts[:date])
+        entry = @schedules.add(target: @opts[:target], prompt: @opts[:prompt], recurrence: recurrence,
+                               title: @opts[:title], mode: @opts[:mode] || Schedules::CHAIN,
+                               catch_up: @opts[:catch_up], keep_links: @opts[:keep_links],
+                               max_failures: @opts[:max_failures], max_skips: @opts[:max_skips])
+      rescue Schedules::Usage => e
+        return usage_error(e.message)
+      rescue Session::AmbiguousId => e
+        return failed("which session? #{e.message}")
+      rescue Session::NotFound
+        return failed("no session #{@opts[:target]}")
+      end
+
+      @stdout.puts("#{entry.id} added: #{entry.target_words} · #{entry.recurrence_words} · next #{clock(entry.next_due)}")
+      CLI::Exit::OK
+    end
+
+    def list
+      entries = @schedules.entries(include_disabled: @opts[:include_disabled] ? true : false)
+      if @opts[:format] == "json"
+        @stdout.puts(JSON.pretty_generate(entries.map { |entry| entry_line_json(entry) }))
+        return CLI::Exit::OK
+      end
+      if entries.empty?
+        @stdout.puts("no schedules")
+        return CLI::Exit::OK
+      end
+      entries.each { |entry| @stdout.puts(entry_line(entry)) }
+      CLI::Exit::OK
+    end
+
+    def show
+      id = @args.first || @opts[:id]
+      return usage_error("show needs a schedule id") if id.to_s.strip.empty?
+
+      entry = @schedules.lookup(id)
+      return failed("no schedule #{id}") if entry.nil?
+
+      @stdout.puts("#{entry.id}  #{entry.title || "(untitled)"}")
+      @stdout.puts("  anchor: #{entry.anchor}  head: #{entry.head}  mode: #{entry.mode}")
+      @stdout.puts("  recurrence: #{entry.recurrence_words}  next due: #{clock(entry.next_due)}")
+      @stdout.puts("  last fired: #{clock(entry.last_fired)}  last result: #{entry.last_result || "-"}")
+      @stdout.puts("  skips: #{entry.skips} of #{entry.max_skips}  failures: #{entry.failures} of #{entry.max_failures}")
+      @stdout.puts("  keep_links: #{entry.keep_links}  enabled: #{entry.enabled}")
+      @stdout.puts("  prompt: #{entry.prompt}")
+      CLI::Exit::OK
+    rescue Schedules::Usage => e
+      usage_error(e.message)
+    end
+
+    def tick
+      result = @schedules.tick(dry_run: @opts[:dry_run] ? true : false)
+      if @opts[:format] == "json"
+        @stdout.puts(JSON.pretty_generate({ "locked" => result.locked, "outcomes" => result.outcomes.map { |outcome| { "id" => outcome.id, "status" => outcome.status, "detail" => outcome.detail } } }))
+        return CLI::Exit::OK
+      end
+
+      if result.locked
+        @stdout.puts("no schedules due (another tick holds the lock)")
+        return CLI::Exit::OK
+      end
+      if result.outcomes.empty?
+        @stdout.puts("no schedules due")
+        return CLI::Exit::OK
+      end
+
+      result.outcomes.each do |outcome|
+        word = outcome.status == "dry" ? "would fire" : outcome.status
+        @stdout.puts("#{outcome.id}  #{word}  #{outcome.detail}")
+      end
+      CLI::Exit::OK
+    end
+
+    def act
+      id = @args.first
+      return usage_error("#{@argv[0]} needs a schedule id") if id.to_s.strip.empty?
+
+      result = yield(id)
+      return failed("no schedule #{id}") if result.nil?
+
+      if result.is_a?(Schedules::Outcome)
+        @stdout.puts("#{id}: #{result.status} · #{result.detail}")
+        return result.status == "failed" ? CLI::Exit::FAILED : CLI::Exit::OK
+      end
+
+      @stdout.puts("#{id} #{@argv[0]}: ok")
+      CLI::Exit::OK
+    rescue Schedules::Usage => e
+      usage_error(e.message)
+    end
+
+    def failed(message)
+      error_line(message)
+      CLI::Exit::FAILED
+    end
+
+    def clock(iso)
+      return "-" if iso.nil? || iso.to_s.empty?
+
+      Time.iso8601(iso.to_s).localtime.strftime("%Y-%m-%d %H:%M")
+    rescue ArgumentError
+      iso.to_s
+    end
+
+    def entry_line(entry)
+      note = ""
+      note += " skips #{entry.skips} of #{entry.max_skips} (#{skip_window(entry)})" if entry.skips.positive?
+      note += " disabled after #{entry.failures} failures" unless entry.enabled
+      "#{entry.id}  #{entry.mode}  #{entry.recurrence_words}  #{clock(entry.next_due)}  #{entry.head[0, 8]}#{note}"
+    end
+
+    # A skip budget as a time window: 3 of 12 at a 5 minute tick is about 1 hour
+    # of patience, which is what the count really measures.
+    def skip_window(entry)
+      minutes = entry.max_skips * Schedules.tick_interval_minutes
+      hours = minutes / 60.0
+      hours >= 1 ? "≈#{(hours * 10).round / 10} h at a #{Schedules.tick_interval_minutes} min tick" : "≈#{minutes} min"
+    end
+
+    def entry_line_json(entry)
+      entry.to_h.transform_keys(&:to_s).merge(
+        "recurrence_words" => entry.recurrence_words,
+        "skip_window" => skip_window(entry)
+      )
+    end
+  end
+end