agent-lock 0.2.1

data/lib/agent/lock/record.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "process_info"
+require_relative "scope"
+
+require "yaml"
+require "time"
+require "digest"
+require "socket"
+
+module Agent
+  module Lock
+    # One lock, on disk.
+    #
+    # A markdown file with YAML front matter, rather than plain YAML, because
+    # the interesting half of a lock is the sentence saying what the holder is
+    # doing. An agent that finds a file locked can read that and decide whether
+    # to wait or to work elsewhere; "occupied" tells it nothing. A human
+    # opening the file in an editor sees the same thing.
+    #
+    #     ---
+    #     agent_id: claude-9feca100
+    #     scope: workflow/**
+    #     pid: 69232
+    #     ---
+    #     Rewriting the installer's filter pair.
+    class Record
+      FIELDS = %i[id agent_id parent_agent_id scope tree worktree pid started host
+                  created_at updated_at status frozen_paths].freeze
+
+      ACTIVE = "active"
+      ORPHANED = "orphaned"
+      SEPARATOR = "---"
+      NOTES_HEADING = "## Progress"
+
+      attr_reader(*FIELDS, :intent, :path)
+
+      class << self
+        # @param scope [Scope]
+        # @param tree [Tree]
+        # @param identity [Identity]
+        # @param intent [String]
+        # @return [Record]
+        def build(scope:, tree:, identity:, intent:)
+          evidence = identity.evidence
+          new(
+            id: id_for(tree, scope), agent_id: identity.id, parent_agent_id: identity.parent_id,
+            scope: scope.to_s, tree: tree.root, worktree: tree.worktree?,
+            pid: evidence[:pid], started: evidence[:started], host: evidence[:host],
+            created_at: Time.now.utc.iso8601, status: ACTIVE, frozen_paths: [], intent: intent
+          )
+        end
+
+        # Derived from the tree and the scope so that a second run looking for
+        # the same lock finds it without reading every file in the store.
+        #
+        # @return [String]
+        def id_for(tree, scope)
+          digest = Digest::SHA256.hexdigest("#{tree.root}\0#{scope}")[0, 8]
+          "#{scope.slug}-#{digest}"
+        end
+
+        # @param path [String]
+        # @return [Record, nil] nil for a file this gem did not write
+        def read(path)
+          parse(File.read(path), path: path)
+        rescue Errno::ENOENT, Errno::EISDIR
+          nil
+        end
+
+        # @param text [String] a lock document, from a file or from Redis
+        # @return [Record, nil]
+        def parse(text, path: nil)
+          _, front, body = text.to_s.split(/^#{SEPARATOR}\s*$/, 3)
+          data = YAML.safe_load(front.to_s, permitted_classes: [], aliases: false)
+          return nil unless data.is_a?(Hash)
+
+          new(**data.transform_keys(&:to_sym).slice(*FIELDS), intent: body.to_s.strip, path: path)
+        rescue Psych::Exception, ArgumentError
+          nil
+        end
+      end
+
+      def initialize(intent: "", path: nil, **fields)
+        FIELDS.each { |field| instance_variable_set(:"@#{field}", fields[field]) }
+        @frozen_paths = Array(@frozen_paths)
+        @intent = intent.to_s
+        @path = path
+      end
+
+      # @param changes [Hash] fields to replace
+      # @return [Record] a copy, since a record on disk is not edited in place
+      def with(intent: self.intent, **changes)
+        fields = FIELDS.to_h { |field| [field, public_send(field)] }
+        self.class.new(**fields, **changes, intent: intent, path: path)
+      end
+
+      # @return [String] the file's whole content
+      def to_markdown
+        front = FIELDS.to_h { |field| [field.to_s, public_send(field)] }.compact
+        "#{YAML.dump(front)}#{SEPARATOR}\n\n#{intent.strip}\n"
+      end
+
+      # @return [Boolean] the holder is gone, but the work it recorded is not
+      def orphaned? = status == ORPHANED
+
+      # @return [Boolean] a claim anybody has to respect. An orphaned lock is a
+      #   message left for whoever comes next, not a claim, so it blocks nobody.
+      def active? = !orphaned?
+
+      # What the holder has written down since taking the lock.
+      #
+      # A lock outlives a reboot; the session that took it does not. Notes are
+      # kept in the lock itself, with the same lifespan, so that coming back to
+      # a tree after a crash is reading one file rather than guessing.
+      #
+      # @param text [String]
+      # @return [Record] a copy carrying the note
+      def note(text)
+        body = notes? ? intent : "#{intent}\n\n#{NOTES_HEADING}"
+        with(intent: "#{body}\n- #{Time.now.utc.iso8601} #{text.strip}", updated_at: Time.now.utc.iso8601)
+      end
+
+      # @return [Boolean] whether anything worth keeping was written down
+      def notes? = intent.include?(NOTES_HEADING)
+
+      # @return [Scope]
+      def scope_object = @scope_object ||= Scope.new(scope)
+
+      # Two different questions, deliberately not one.
+      #
+      # Ownership answers "may I release this, write notes in it, and does
+      # `mine` list it": yes for my own locks and my sub-agents', never for my
+      # parent's. A session cleaning up after itself has to be able to take
+      # its children's locks with it, or a crashed sub-agent's claim outlives
+      # everybody. The reverse is how a child's `release-all` used to drop the
+      # umbrella its parent had just fanned out under.
+      #
+      # @param identity [Identity]
+      # @return [Boolean]
+      def held_by?(identity) = mine?(identity) || descendant_of?(identity)
+
+      # Blocking answers "may I claim an overlapping scope": everything except
+      # my own lock and my parent's. The one that matters is the sibling: two
+      # sub-agents of one session, let loose in the same tree, are exactly the
+      # pair this gem exists to keep apart, and treating the whole family as
+      # one holder would let them write over each other freely.
+      #
+      # A child's lock blocks its parent too. The parent handed that scope out;
+      # taking it back while the child is still in there is the same collision
+      # from the other direction.
+      #
+      # @param identity [Identity]
+      # @return [Boolean]
+      def blocks?(identity) = !(mine?(identity) || ancestor_of?(identity))
+
+      # @return [Boolean] the holder's process is still running, on this host
+      def alive?
+        return true unless same_host?
+
+        ProcessInfo.alive?(pid, started: started)
+      end
+
+      # Whether the claim is void, so reaping it takes nothing from anybody.
+      #
+      # On this host the holder can be asked, and its answer is the only one
+      # that counts: a live holder's lock is never expired, however old. Age
+      # used to count here too, measured from `created_at`, so a session two
+      # hours into a refactor lost its lock mid-edit and the next agent walked
+      # straight in. A holder on another host cannot be asked, so time is all
+      # there is, measured from its last write so that notes act as a
+      # heartbeat.
+      #
+      # @param minutes [Integer] how long an unverifiable lock is trusted
+      # @return [Boolean]
+      def expired?(minutes) = same_host? ? !alive? : untouched_for?(minutes)
+
+      # A claim still standing, whose holder has not touched it in longer than
+      # anybody should need. Reported, never acted on: the holder may be alive
+      # and simply slow, so breaking it is a decision somebody announces.
+      #
+      # @param minutes [Integer]
+      # @return [Boolean]
+      def stale?(minutes) = active? && untouched_for?(minutes)
+
+      # @return [String] one line, for a listing
+      def summary
+        where = worktree ? "#{tree} (worktree)" : tree
+        "#{scope}\t#{agent_id}\t#{created_at}\t#{where}"
+      end
+
+      private
+
+      def mine?(identity) = agent_id == identity.id
+
+      # The lock belongs to the session that spawned this one.
+      def ancestor_of?(identity) = !identity.parent_id.nil? && agent_id == identity.parent_id
+
+      # The lock belongs to a sub-agent this session spawned.
+      def descendant_of?(identity) = !parent_agent_id.nil? && parent_agent_id == identity.id
+
+      def same_host? = host.nil? || host == Socket.gethostname
+
+      # A lock with no readable timestamp is left alone rather than guessed
+      # at: reaping on a parse error would delete live claims.
+      def untouched_for?(minutes)
+        touched = updated_at || created_at
+        return false if touched.nil?
+
+        Time.now.utc - Time.parse(touched) > minutes * 60
+      rescue ArgumentError
+        false
+      end
+    end
+  end
+end

data/lib/agent/lock/scope.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Agent
+  module Lock
+    # What a lock covers: one path, or a glob over many.
+    #
+    # `**` is the whole tree, `workflow/**` a corner of it, `lib/a.rb` a single
+    # file. A directory is taken to mean everything under it, since an agent
+    # that says it is working in `docs` is not promising to leave `docs/api`
+    # alone.
+    #
+    # Two scopes conflict when either one's fixed part contains the other's.
+    # `workflow/**` and `workflow/lib/cli.rb` conflict; `docs/**` and
+    # `workflow/**` do not. Comparing the fixed parts rather than trying to
+    # intersect two globs is deliberate: glob intersection has answers nobody
+    # can predict, and the failure it would buy is two agents editing one file.
+    # This errs the other way, toward refusing work that might have been safe.
+    class Scope
+      # A scope the tree cannot honestly lock: empty, or somewhere else. Raised
+      # rather than guessed at, since every guess so far locked the wrong thing
+      # and reported success. An `Error`, so the launcher exits 2 with the
+      # message, which is written for the agent that has to fix its argument.
+      class Invalid < Error; end
+
+      ALL = "**"
+
+      # The spellings of the whole tree, taken literally wherever the agent
+      # stands.
+      WHOLE_TREE = [".", "*", ALL].freeze
+
+      EMPTY = "empty scope: pass ** to claim the whole tree"
+
+      # @return [String] the pattern, relative to the tree root
+      attr_reader :pattern
+
+      class << self
+        # What the user typed, as a pattern relative to the tree root.
+        #
+        # An empty scope used to mean the whole tree, so `alock acquire "$SCOPE"`
+        # with the variable unset claimed everything, and nobody asked for
+        # that. Globs used to skip the tree entirely, so `../x/**` was stored
+        # verbatim and `/abs/tree/lib/**` never met `lib/**`. Both are read
+        # the way a plain path is now.
+        #
+        # @param path [String] a path or a glob, absolute or relative
+        # @param tree [Tree]
+        # @return [Scope]
+        # @raise [Invalid] when the scope is empty, or resolves outside the tree
+        def parse(path, tree:)
+          text = path.to_s.strip
+          raise Invalid, EMPTY if text.empty?
+          return new(ALL) if WHOLE_TREE.include?(text)
+
+          text = glob?(text) ? relative_glob(text, tree) : tree.relative(text)
+          return new(ALL) if text == "."
+
+          text = "#{text}/#{ALL}" if directory?(text, tree)
+          new(text)
+        end
+
+        # @param text [String]
+        # @return [Boolean] whether it has a wildcard anywhere in it
+        def glob?(text) = text.match?(/[*?\[{]/)
+
+        # @param text [String] relative to the tree root
+        # @param tree [Tree]
+        # @return [Boolean] a plain path naming a directory that exists
+        def directory?(text, tree)
+          return false if glob?(text)
+
+          File.directory?(File.join(tree.root, text))
+        end
+
+        private
+
+        # A glob with its fixed part, everything before the segment holding
+        # the first wildcard, read through the tree as a plain path would be.
+        # The wildcards are kept as typed.
+        #
+        # @param text [String] a glob, absolute or relative
+        # @param tree [Tree]
+        # @return [String] the glob relative to the tree root
+        # @raise [Invalid] when the fixed part is outside the tree, or a `..`
+        #   follows a wildcard
+        def relative_glob(text, tree)
+          fixed, wild = split(text)
+          # The fixed part is what was checked against the tree; a `..` after a
+          # wildcard climbs past it to somewhere nobody checked.
+          if wild.split("/").include?("..")
+            raise Invalid, "#{text}: a .. after a wildcard could leave the tree; spell the path without it"
+          end
+
+          base = tree.relative(fixed.empty? ? "." : fixed)
+          base == "." ? wild : "#{base}/#{wild}"
+        end
+
+        # @param text [String] a glob
+        # @return [Array(String, String)] the fixed part, "/" for a glob at the
+        #   filesystem root, and the rest from the first wildcard's segment on
+        def split(text)
+          cut = text.rindex("/", text.index(/[*?\[{]/))
+          return ["", text] if cut.nil?
+          return ["/", text[1..]] if cut.zero?
+
+          [text[0...cut], text[(cut + 1)..]]
+        end
+      end
+
+      def initialize(pattern)
+        @pattern = pattern.to_s.squeeze("/").delete_prefix("./")
+      end
+
+      # The leading segments with no wildcard in them, which is the deepest
+      # directory a pattern is certainly confined to.
+      #
+      # @return [String] "" for a pattern that starts with a wildcard
+      def fixed_part
+        @fixed_part ||= pattern.split("/").take_while { |part| !self.class.glob?(part) }.join("/")
+      end
+
+      # @param other [Scope]
+      # @return [Boolean]
+      def conflicts_with?(other)
+        return true if pattern == other.pattern
+
+        contains?(fixed_part, other.fixed_part) || contains?(other.fixed_part, fixed_part)
+      end
+
+      # Whether holding this scope already means holding `other`, which is a
+      # stricter question than whether the two overlap. Only a scope that
+      # takes everything under a directory can promise that; a partial glob
+      # such as `lib/*.rb` covers nothing but itself, since working out what
+      # else it matches is the guessing #conflicts_with? refuses to do.
+      #
+      # @example
+      #   Scope.new("lib/**").covers?(Scope.new("lib/cli.rb"))   # => true
+      #   Scope.new("lib/cli.rb").covers?(Scope.new("lib/**"))   # => false
+      #
+      # @param other [Scope]
+      # @return [Boolean]
+      def covers?(other)
+        return true if pattern == other.pattern
+
+        recursive? && contains?(fixed_part, other.fixed_part)
+      end
+
+      # @return [Boolean] the whole tree, or everything under one directory
+      def recursive? = [ALL, "#{fixed_part}/#{ALL}"].include?(pattern)
+
+      # @return [String] safe to use in a filename
+      def slug
+        text = pattern.gsub("**", "all").gsub(%r{[^A-Za-z0-9._/-]}, "").tr("/", "-").squeeze("-")
+        text = text.delete_prefix("-").delete_suffix("-")
+        text.empty? ? "tree" : text[0, 60]
+      end
+
+      def to_s = pattern
+
+      def ==(other) = other.is_a?(Scope) && pattern == other.pattern
+
+      private
+
+      # @return [Boolean] whether `outer` is `inner` or an ancestor of it
+      def contains?(outer, inner)
+        return true if outer.empty? || outer == inner
+
+        inner.start_with?("#{outer}/")
+      end
+    end
+  end
+end

data/lib/agent/lock/skill.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Agent
+  module Lock
+    # The skill this gem ships: a SKILL.md that teaches an agent how to claim
+    # files with `alock`, copied into whichever skills directory the agent reads.
+    #
+    # It lives inside the gem rather than in a repository of its own so that
+    # the instructions an agent follows can never describe a different version
+    # of the tool than the one it runs.
+    #
+    # @example
+    #   Agent::Lock::Skill.new(into: "~/.claude/skills").install.status  # => :installed
+    class Skill
+      # The skill's directory name, which is also the name it answers to.
+      NAME = "agent-lock"
+
+      # Where the gem keeps its skills, one directory each.
+      ROOT = File.expand_path("../../../skills", __dir__)
+
+      # What #install did, and where.
+      Result = Data.define(:status, :path) do
+        # @return [Integer] 1 when the install was refused, 0 otherwise
+        def code = %i[differs linked].include?(status) ? 1 : 0
+      end
+
+      class << self
+        # @return [String] the bundled skill's directory
+        def source = File.join(ROOT, NAME)
+
+        # @return [String] where most agents other than Claude Code look for
+        #   a user's own skills; the CLI's `--for claude` points at
+        #   `~/.claude/skills` instead
+        def default_into = File.join(Dir.home, ".agents", "skills")
+      end
+
+      # @return [String] the skills directory being installed into
+      attr_reader :into
+
+      # @return [String] the skill directory being copied
+      attr_reader :source
+
+      # @param into [String] a skills directory, such as ~/.claude/skills
+      # @param source [String] the skill to copy, the bundled one by default
+      def initialize(into: self.class.default_into, source: self.class.source)
+        @into = File.expand_path(into)
+        @source = source
+      end
+
+      # @return [String] the directory the skill ends up in
+      def target = File.join(into, NAME)
+
+      # Copy the skill in, unless something is already there that this would
+      # destroy. A copy that differs may be one somebody edited on purpose,
+      # and a symlink is another installer's, such as a dotfiles repository
+      # that links every skill it manages; replacing either without being
+      # asked is the silent last-writer-wins this gem exists to prevent.
+      #
+      # @param force [Boolean] replace a copy that differs; never a symlink
+      # @return [Result] :installed, :current, :differs or :linked
+      def install(force: false)
+        refused = refusal(force)
+        return refused if refused
+
+        FileUtils.rm_rf(target)
+        FileUtils.mkdir_p(into)
+        FileUtils.cp_r(source, target)
+        result(:installed)
+      end
+
+      private
+
+      # @param force [Boolean]
+      # @return [Result, nil] why nothing should be copied, or nil to go ahead
+      def refusal(force)
+        return result(:linked) if File.symlink?(target)
+        return result(:current) if current?
+
+        result(:differs) if File.exist?(target) && !force
+      end
+
+      # @param status [Symbol]
+      # @return [Result]
+      def result(status) = Result.new(status: status, path: target)
+
+      # @return [Boolean] the same files are there, byte for byte
+      def current?
+        return false unless File.directory?(target)
+
+        wanted = files(source)
+        wanted == files(target) &&
+          wanted.all? { |rel| FileUtils.compare_file(File.join(source, rel), File.join(target, rel)) }
+      end
+
+      # @param dir [String]
+      # @return [Array<String>] every file under it, relative and sorted
+      def files(dir)
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: dir).select { |rel| File.file?(File.join(dir, rel)) }.sort
+      end
+    end
+  end
+end

data/lib/agent/lock/store/file_system_store.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../record"
+
+require "fileutils"
+
+module Agent
+  module Lock
+    module Store
+      # Locks as files, which is the default and the one that needs nothing
+      # installed. See Tree#store_dir for why they live inside `.git`.
+      class FileSystemStore
+        SUFFIX = ".lock.md"
+        MUTEX = ".mutex"
+
+        # Seconds. A claim's critical section is a directory scan and one
+        # write, so anything near this is somebody stuck, not somebody busy.
+        MUTEX_TIMEOUT = 15
+
+        attr_reader :tree
+
+        def initialize(tree)
+          @tree = tree
+        end
+
+        # @return [String]
+        def dir = tree.store_dir
+
+        # @return [String] how a listing names this store
+        def describe = dir
+
+        # FNM_DOTMATCH is load-bearing. A scope like `.plans/**` slugs to a
+        # filename that starts with a dot, and a plain glob skips it, so the
+        # lock was written, listed nowhere, and blocked nobody. Redis matches
+        # those keys either way, and a store that enumerates less than it holds
+        # is worse than no store at all.
+        #
+        # @return [Array<Record>] every lock here, other worktrees included
+        def all
+          Dir.glob(File.join(dir, "*#{SUFFIX}"), File::FNM_DOTMATCH)
+             .sort
+             .filter_map { |path| Record.read(path) }
+        end
+
+        # Runs the block with every other process in this store shut out, so a
+        # scan for conflicts and the write it justifies cannot be interleaved.
+        # O_EXCL alone settles a race for one scope, but `lib/**` and
+        # `lib/a1.rb` are two files, and two agents that both scanned an empty
+        # store before either wrote both won.
+        #
+        # An exclusive flock on `.mutex` beside the locks. The kernel drops it
+        # when the holder exits, crash included, so a dead agent cannot leave
+        # the store wedged. A live one that stops mid-claim can, which is why
+        # the wait is bounded and ends in an error rather than a hung agent.
+        #
+        # Not re-entrant. flock belongs to an open file, not to a process, so
+        # a nested call opens a second one, waits on the first, and raises
+        # once the timeout runs out.
+        #
+        # @yield the critical section
+        # @return [Object] whatever the block returns
+        # @raise [Error] when the mutex stayed held for longer than the timeout
+        def synchronize
+          FileUtils.mkdir_p(dir)
+          # Closing the file releases the flock, and the block form closes it
+          # on the way out whether the critical section returned or raised.
+          File.open(mutex_path, File::RDWR | File::CREAT, 0o644) do |file|
+            wait_for(file)
+            yield
+          end
+        end
+
+        # @param scope [Scope]
+        # @return [Record, nil]
+        def find(scope) = Record.read(path_for(Record.id_for(tree, scope)))
+
+        # Atomic: two agents racing for one scope cannot both win, because only
+        # one File::EXCL create succeeds.
+        #
+        # @param record [Record]
+        # @return [Boolean] false when somebody else got there first
+        def create(record)
+          FileUtils.mkdir_p(dir)
+          File.open(path_for(record.id), File::WRONLY | File::CREAT | File::EXCL) do |file|
+            file.write(record.to_markdown)
+          end
+          true
+        rescue Errno::EEXIST
+          false
+        end
+
+        # Replace a lock in place. Written beside itself and renamed, so a
+        # reader never sees half a document, and so a crash mid-write leaves
+        # the previous version rather than nothing.
+        #
+        # @param record [Record]
+        # @return [void]
+        def update(record)
+          path = record.path || path_for(record.id)
+          temp = "#{path}.#{Process.pid}.tmp"
+          File.write(temp, record.to_markdown)
+          File.rename(temp, path)
+        end
+
+        # @param record [Record]
+        # @return [void]
+        def delete(record) = FileUtils.rm_f(record.path || path_for(record.id))
+
+        # @param id [String]
+        # @return [String]
+        def path_for(id) = File.join(dir, "#{id}#{SUFFIX}")
+
+        # Named so that `all`'s `*.lock.md` can never match it, dot or no dot.
+        #
+        # @return [String]
+        def mutex_path = File.join(dir, MUTEX)
+
+        private
+
+        # Polls with a non-blocking flock rather than blocking on it, because
+        # a blocking flock cannot be given up on: an agent stuck behind a
+        # stopped `alock` would wait forever with nothing on its screen.
+        #
+        # @param file [File] the open mutex
+        # @return [void]
+        # @raise [Error] once the timeout has passed
+        def wait_for(file)
+          timeout = mutex_timeout
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          delay = 0.005
+          until file.flock(File::LOCK_EX | File::LOCK_NB)
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+              raise Error, format("timed out after %<timeout>gs waiting for %<path>s, " \
+                                  "which another process claiming a lock is holding", timeout:, path: mutex_path)
+            end
+
+            # Jittered, so that processes which all lost the same round do not
+            # all come back for the next one at the same instant.
+            sleep(delay * rand(0.5..1.0))
+            delay = [delay * 2, 0.1].min
+          end
+        end
+
+        # @return [Float] seconds to wait for the mutex before giving up
+        # @raise [Error] when AGENT_LOCK_MUTEX_TIMEOUT is not a finite,
+        #   non-negative number: `Float` accepts "Infinity" and "NaN", and
+        #   either makes the deadline below unreachable, hanging the poll
+        #   loop forever instead of timing out.
+        def mutex_timeout
+          timeout = Float(ENV.fetch("AGENT_LOCK_MUTEX_TIMEOUT", MUTEX_TIMEOUT))
+          unless timeout.finite? && timeout >= 0
+            raise Error, "AGENT_LOCK_MUTEX_TIMEOUT must be a finite, non-negative number, got #{timeout}"
+          end
+
+          timeout
+        end
+      end
+    end
+  end
+end