agent-lock 0.2.1

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

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../record"
+
+require "redis"
+require "digest"
+require "securerandom"
+
+module Agent
+  module Lock
+    module Store
+      # The same locks in a local Redis, for the machines that already run one.
+      #
+      # Redis buys two things the filesystem cannot: `SET NX` is atomic across
+      # machines rather than only across processes on one, and a TTL expires an
+      # abandoned lock without anybody having to reason about whether its holder
+      # is still alive. It costs the thing that makes the file store pleasant,
+      # which is that you can `cat` a lock, so the value stored is the same
+      # markdown document either way.
+      #
+      # Picked with AGENT_LOCK_BACKEND=redis, or by default when one answers on
+      # REDIS_URL. See Store's moduledoc for how that default is decided.
+      class RedisStore
+        NAMESPACE = "agent-lock"
+
+        # How long the store mutex outlives a holder that died holding it. A
+        # claim's critical section is a SCAN and one SET, so ten seconds is
+        # somebody gone, not somebody busy.
+        MUTEX_LEASE_MS = 10_000
+
+        # Seconds to wait for the mutex. Longer than the lease, so that a
+        # crashed holder is waited out rather than reported.
+        MUTEX_TIMEOUT = 15
+
+        LEASE_LOST = "the lock store's mutex lease (#{MUTEX_LEASE_MS}ms) ran out before the claim finished, " \
+                     "so another process may have claimed an overlapping scope: check the listing".freeze
+
+        RELEASE = <<~LUA
+          if redis.call("GET", KEYS[1]) == ARGV[1] then
+            return redis.call("DEL", KEYS[1])
+          end
+          return 0
+        LUA
+
+        attr_reader :tree, :client
+
+        def initialize(tree, client: nil)
+          @tree = tree
+
+          if client.nil?
+            client, error = self.class.create_client
+            raise(error) if client.nil? && error
+
+            @client = client if client
+          else
+            @client = client
+          end
+
+          raise "no functional Redis client could be created for #{self.class.url}" unless @client
+        end
+
+        # @return [String]
+        def describe = "redis #{url} (#{namespace})"
+
+        # SCAN rather than KEYS: this runs on whatever Redis the machine
+        # already has, which may be somebody's shared development instance,
+        # and KEYS blocks the server for the length of the scan.
+        #
+        # @return [Array<Record>]
+        def all
+          keys = client.scan_each(match: "#{namespace}:*").to_a.uniq.sort
+          keys.filter_map { |key| parse(client.get(key), key) }
+        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.
+        # SET NX alone settles a race for one scope, but `lib/**` and
+        # `lib/a1.rb` are two keys, and two agents that both scanned an empty
+        # namespace before either wrote both won.
+        #
+        # The mutex is a key set with NX to a token only this call knows, and
+        # leased rather than held: a holder that dies mid-claim cannot release
+        # it, so the lease does, within MUTEX_LEASE_MS. The wait for it is
+        # bounded, and longer than the lease, so a crashed holder costs the
+        # next agent a pause and never an error.
+        #
+        # Not re-entrant. A nested call waits on its own mutex until the lease
+        # frees it, and the outer call then finds it gone and raises.
+        #
+        # @yield the critical section
+        # @return [Object] whatever the block returns
+        # @raise [Error] when the mutex stayed held for longer than the timeout,
+        #   or the block outlived its lease and ran unprotected for a while
+        def synchronize
+          token = SecureRandom.hex(16)
+          wait_for(token)
+          begin
+            outcome = yield
+          ensure
+            released = release(token)
+          end
+          raise Error, LEASE_LOST unless released
+
+          outcome
+        end
+
+        # Outside the namespace on purpose. `all` scans `<namespace>:*`, and a
+        # mutex inside it would be read back as a lock on every scan.
+        #
+        # @return [String]
+        def mutex_key = "#{NAMESPACE}-mutex:#{digest}"
+
+        # @param scope [Scope]
+        # @return [Record, nil]
+        def find(scope) = parse(client.get(key_for(Record.id_for(tree, scope))), nil)
+
+        # Named to match the Store interface FileSystemStore shares: an action
+        # with a boolean outcome, not a pure predicate.
+        #
+        # @param record [Record]
+        # @return [Boolean]
+        # rubocop:disable-next Naming/PredicateMethod
+        def create(record)
+          args = { nx: true }
+          args[:ex] = ttl_seconds if ttl_seconds.positive?
+          !!client.set(key_for(record.id), record.to_markdown, **args)
+        end
+
+        # @param record [Record]
+        # @return [void]
+        def update(record) = client.set(key_for(record.id), record.to_markdown, keepttl: true)
+
+        # @param record [Record]
+        # @return [void]
+        def delete(record) = client.del(key_for(record.id))
+
+        # @param id [String]
+        # @return [String]
+        def key_for(id) = "#{namespace}:#{id}"
+
+        private
+
+        # Keyed by the tree, so one Redis instance serves every checkout on the
+        # machine without their locks colliding.
+        def namespace = "#{NAMESPACE}:#{digest}"
+
+        # @return [String]
+        def url = self.class.url
+
+        def digest = ::Digest::SHA256.hexdigest(tree.root)[0, 12]
+
+        # SET NX PX until it takes, backing off with jitter so that processes
+        # which all lost the same round do not all come back for the next one
+        # at the same instant.
+        #
+        # @param token [String] what the key is set to, so release can tell
+        #   this holder's mutex from the next one's
+        # @return [void]
+        # @raise [Error] once the timeout has passed
+        def wait_for(token)
+          timeout = mutex_timeout
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+          delay = 0.005
+          until client.set(mutex_key, token, nx: true, px: MUTEX_LEASE_MS)
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+              raise Error, format("timed out after %<timeout>gs waiting for %<key>s in %<url>s, " \
+                                  "which another process claiming a lock is holding", timeout:, key: mutex_key, url:)
+            end
+
+            sleep(delay * rand(0.5..1.0))
+            delay = [delay * 2, 0.1].min
+          end
+        end
+
+        # Compare and delete in one step. A plain DEL after a GET could land
+        # after the lease ran out and somebody else took the mutex, and would
+        # then let a third process in beside the second.
+        #
+        # @param token [String]
+        # @return [Boolean] false when the mutex was no longer this holder's
+        # rubocop:disable-next Naming/PredicateMethod
+        def release(token) = client.eval(RELEASE, keys: [mutex_key], argv: [token]) == 1
+
+        # @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 in `wait_for` 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
+
+        def ttl_seconds = Integer(ENV.fetch("AGENT_LOCK_TTL_SECONDS", 0))
+
+        def parse(text, key)
+          return nil if text.nil?
+
+          record = Record.parse(text)
+          record && key ? record.with(id: key.split(":").last) : record
+        end
+
+        class << self
+          def url = ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0")
+
+          # @return Array[RedisClient,NilClass,Exception] the client if it could be created,
+          # or the error that prevented it
+          def create_client
+            @client ||= ::Redis.new(url: url).tap do |client|
+              _version = client.info["redis_version"]
+            end
+            [@client, nil]
+          rescue Redis::CannotConnectError, Redis::BaseError, Errno::ECONNREFUSED, SocketError => e
+            [nil, e]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/store.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "store/file_system_store"
+require_relative "store/redis_store"
+
+require "fileutils"
+
+module Agent
+  module Lock
+    # Where locks are kept. One tree, one store, chosen on purpose.
+    #
+    # AGENT_LOCK_BACKEND wins when set. Otherwise a tree that already has a
+    # marker keeps using it. A virgin tree defaults to Redis when one answers
+    # locally, file when none does.
+    #
+    # That default is still never a runtime auto-*switch*: once a marker
+    # exists, every later process in that tree is bound to it regardless of
+    # what Redis is doing, because an agent that quietly moved to a different
+    # store than the agent beside it would give the two of them two stores in
+    # which neither can see the other's locks, a lock that is worse than no
+    # lock, because it reports success.
+    #
+    # The one moment that default is decided is also the one moment two
+    # processes could race: both find a virgin tree, both probe Redis, and a
+    # flaky answer could hand them different defaults before either writes the
+    # marker. So the marker is claimed atomically (first `O_CREAT|O_EXCL` wins)
+    # and every process builds from whatever ends up on disk, never from its
+    # own guess, so a race can pick either backend but never a split.
+    module Store
+      MARKER = "backend"
+
+      class Mismatch < Error; end
+
+      module_function
+
+      # @param tree [Tree]
+      # @return [Store::FileSystemStore, Store::RedisStore]
+      def for(tree)
+        requested = ENV["AGENT_LOCK_BACKEND"]&.downcase
+        established = recorded(tree)
+
+        if established
+          if requested && requested != established
+            raise Mismatch, "this tree's locks live in #{established}, not #{requested}, " \
+                            "release them before switching backends"
+          end
+
+          return build(established, tree)
+        end
+
+        build(claim(tree, requested || default_backend), tree)
+      end
+
+      # @return [Store::FileSystemStore, Store::RedisStore]
+      def build(name, tree)
+        case name
+        when "redis" then RedisStore.new(tree)
+        when "file" then FileSystemStore.new(tree)
+        else raise Mismatch, "unknown backend #{name.inspect}, expected file or redis"
+        end
+      end
+
+      # @return [String, nil] the backend this tree already uses
+      def recorded(tree)
+        path = marker_path(tree)
+        File.exist?(path) ? File.read(path).strip : nil
+      rescue SystemCallError
+        nil
+      end
+
+      # Atomically claims the marker for a virgin tree with `name`, or, when a
+      # concurrent process already claimed it first, reads back whatever that
+      # process wrote instead. Either way, every caller ends up building the
+      # same backend for this tree.
+      #
+      # @param tree [Tree]
+      # @param name [String] this process's proposed backend
+      # @return [String] the backend actually recorded, which may not be `name`
+      def claim(tree, name)
+        path = marker_path(tree)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{name}\n", mode: File::WRONLY | File::CREAT | File::EXCL)
+        name
+      rescue Errno::EEXIST
+        recorded(tree) || name
+      rescue SystemCallError
+        name
+      end
+
+      def marker_path(tree) = File.join(tree.store_dir, MARKER)
+
+      # @return [String] "redis" when one answers on REDIS_URL, "file" otherwise
+      def default_backend
+        local_redis_available? ? "redis" : "file"
+      end
+
+      def local_redis_available?
+        client, error = RedisStore.create_client
+        !client.nil? && error.nil?
+      end
+    end
+  end
+end

data/lib/agent/lock/tree.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "scope"
+
+module Agent
+  module Lock
+    # The working tree a lock is about, and where its locks are kept.
+    #
+    # Locks live in `<git-common-dir>/agent-locks`, which is chosen rather than
+    # `~/.agent-locks` or a dotfile at the root for three reasons. Git cannot
+    # track anything inside `.git`, so no repository needs a `.gitignore` line
+    # and `git clean -xdf` cannot wipe the locks. Every worktree of a
+    # repository resolves `--git-common-dir` to the same directory, so one
+    # store serves all of them. And it dies with the checkout, instead of
+    # outliving it in a home directory nobody thinks to sweep.
+    #
+    # Outside a repository the store falls back to `~/.agent-locks`, keyed by a
+    # digest of the tree, since there is no `.git` to hide in.
+    class Tree
+      class << self
+        # @param dir [String] anywhere inside the tree
+        # @return [Tree]
+        def for(dir = Dir.pwd) = new(dir)
+      end
+
+      # @return [String] absolute, symlinks resolved, so /tmp and /private/tmp
+      #   cannot become two names for one tree
+      attr_reader :root
+
+      def initialize(dir = Dir.pwd)
+        @dir = File.realpath(dir)
+        @root = git("rev-parse", "--show-toplevel") || @dir
+        @root = File.realpath(@root)
+      end
+
+      # @return [Boolean] a linked worktree rather than the original checkout
+      def worktree? = !git_dir.nil? && git_dir != common_dir
+
+      # @description Resolves the directory where locks are stored by either
+      # $AGENT_LOCK_DIR environment variable if defined, or 'agent-locks'
+      # inside .git if available, or the ~/.agent-locks/<tree-digest> in user's
+      # home folder.
+      # @return [String] where locks for this tree are written
+      def store_dir
+        return File.expand_path(ENV["AGENT_LOCK_DIR"]) if ENV["AGENT_LOCK_DIR"]
+        return File.join(common_dir, "agent-locks") if common_dir
+
+        File.join(Dir.home, ".agent-locks", ::Digest::SHA256.hexdigest(root)[0, 12])
+      end
+
+      # A path the user typed, read from where they stand, as a name inside
+      # this tree.
+      #
+      # There used to be a fallback to the basename for anything outside the
+      # root, so `/etc/passwd` quietly locked the tree's own `passwd`: an agent
+      # was told it held something it had never asked for, and the thing it had
+      # asked for stayed unguarded. Outside is now an error.
+      #
+      # The path is compared as typed first, then with symlinks resolved, so an
+      # alias of the tree (`/tmp` for `/private/tmp`) is still inside it, while
+      # an in-tree symlink that points elsewhere keeps its in-tree name, which is
+      # what the lock is about. The path need not exist: an agent claims a file
+      # before writing it.
+      #
+      # @param path [String] anything the user typed, absolute or relative
+      # @return [String] that path relative to the root, "." for the root itself
+      # @raise [Scope::Invalid] when the path resolves outside the tree
+      def relative(path)
+        absolute = File.absolute_path(path, @dir)
+        inside(absolute) || inside(resolve(absolute)) ||
+          raise(Scope::Invalid, "#{path} is outside the tree #{root}")
+      end
+
+      private
+
+      # The prefix test that `delete_prefix` alone got wrong: `/repo-other`
+      # starts with `/repo`, so the root is matched only whole or up to a slash.
+      #
+      # @param absolute [String]
+      # @return [String, nil] relative to the root, or nil when outside it
+      def inside(absolute)
+        return "." if absolute == root
+
+        prefix = root.end_with?("/") ? root : "#{root}/"
+        absolute.delete_prefix(prefix) if absolute.start_with?(prefix)
+      end
+
+      # Symlinks resolved in the deepest part of the path that exists, with the
+      # rest appended, since `File.realpath` refuses a file not yet written.
+      #
+      # @param absolute [String]
+      # @return [String]
+      def resolve(absolute)
+        head = absolute
+        tail = []
+        until File.exist?(head)
+          tail.unshift(File.basename(head))
+          head = File.dirname(head)
+        end
+        File.join(File.realpath(head), *tail)
+      rescue SystemCallError
+        absolute
+      end
+
+      def git_dir = @git_dir ||= absolute(git("rev-parse", "--git-dir"))
+
+      def common_dir = @common_dir ||= absolute(git("rev-parse", "--git-common-dir"))
+
+      def absolute(dir)
+        return nil if dir.nil?
+
+        File.realpath(File.absolute_path(dir, @dir))
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def git(*args)
+        out = IO.popen(["git", "-C", @dir, *args], err: File::NULL, &:read).to_s.strip
+        out.empty? ? nil : out
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/agent/lock/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agent
+  module Lock
+    VERSION = "0.2.1"
+  end
+end

data/lib/agent/lock.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# kept deliberate: this gem loads what it needs, in order
+
+require_relative "lock/version"
+require_relative "lock/error"
+
+module Agent
+  # Advisory locks for the several coding agents that end up in one checkout.
+  #
+  # `Agent::Lock` is the library; `agent-lock` is the executable. Everything
+  # the CLI does is a method on Manager, which prints nothing and exits
+  # nothing, so the whole lifecycle is testable without capturing output.
+  module Lock
+  end
+end
+
+require_relative "lock/process_info"
+require_relative "lock/identity"
+require_relative "lock/tree"
+require_relative "lock/scope"
+require_relative "lock/record"
+require_relative "lock/freeze"
+require_relative "lock/skill"
+require_relative "lock/store"
+require_relative "lock/store/file_system_store"
+require_relative "lock/store/redis_store"
+require_relative "lock/manager"
+require_relative "lock/launcher"
+require_relative "lock/cli"

data/sig/agent/lock.rbs

@@ -0,0 +1,6 @@
+module Agent
+  module Lock
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/skills/agent-lock/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: agent-lock
+description: Use when several agents or sub-agents write in one checkout or worktree, before creating or editing files there, when launching sub-agents that will write files, or when `alock` or `agent-lock` answers REFUSED, HELD, STALE or INTERRUPTED WORK.
+---
+
+# Claiming files with alo
+
+## Overview
+
+`alock` (the `agent-lock` gem) keeps agents that share a checkout from writing over each other. A lock is advisory: it protects a file only if every writer claims first, under its own name, in the tree it writes in.
+
+## Four ways a claim silently protects nothing
+
+1. **An unnamed sub-agent signs as its parent.** Sub-agents run inside the parent's process, and every Bash call is a fresh shell, so an `export` from an earlier call is gone. Put the name on the same command line, every time: `AGENT_ID=<your-name> alock ...`. The `(holder: ...)` in the reply must be your name.
+1. **Two siblings with one name are one holder**, and never block each other. Use the name your orchestrator gave you. Given none, pick the task plus four random characters once, such as `shipping-rates-7f3a`, and type that literal on every call; `$RANDOM` in the prefix changes each time.
+1. **A lock in another checkout guards nothing here.** Run `alock` inside the checkout you write in: `cd <checkout> && AGENT_ID=<your-name> alock ...`, or pass `--dir <checkout>`.
+1. **An orchestrator's lock does not keep siblings apart.** It keeps other sessions out. Each sub-agent still claims its own files inside it.
+
+## Recipe
+
+The orchestrator runs `alock` bare, which makes it the parent, and gives each sub-agent a distinct name and the checkout:
+
+```bash
+cd ~/src/shop && alock acquire "src/**" "fanning out the pricing work"
+```
+
+A sub-agent, under the name it was given. Given none, it uses its own task plus four random characters, chosen once and typed the same on every call; never the example below:
+
+```bash
+cd ~/src/shop && AGENT_ID=shipping-rates-7f3a alock whoami                          # id shipping-rates-7f3a, parent inferred
+cd ~/src/shop && AGENT_ID=shipping-rates-7f3a alock acquire "src/shipping/**" "rate tables"
+cd ~/src/shop && AGENT_ID=shipping-rates-7f3a alock note "src/shipping/**" "rates done, specs red"
+cd ~/src/shop && AGENT_ID=shipping-rates-7f3a alock release-all                     # yours and your sub-agents', never your parent's
+```
+
+Write only inside what you claimed, and claim the narrowest scope that covers it. A directory means everything under it; `**` is rarely right. Quote globs.
+
+## Reading the answer
+
+| Reply                                    | Exit | What to do                                                                          |
+| :--------------------------------------- | :--- | :---------------------------------------------------------------------------------- |
+| `ACQUIRED`, `ALREADY YOURS`              | 0    | Write inside the scope                                                              |
+| `REFUSED` then `HELD ... by X`           | 1    | Do not write. Work elsewhere, or tell the human who holds it                        |
+| `REFUSED: ... your parent's whole claim` | 1    | Claim something narrower inside it                                                  |
+| `HELD ... STALE`                         | 1    | The holder is alive but quiet. Ask, or announce, then `alock break`                   |
+| `INTERRUPTED WORK`                       | 1    | `alock resume` takes it over with its notes; `alock break` discards it                  |
+| `alo: ...`                               | 2    | The command could not run: empty scope, a path outside the tree, a backend mismatch |
+
+## Common mistakes
+
+| Mistake                                                             | Result                                                       |
+| :------------------------------------------------------------------ | :----------------------------------------------------------- |
+| `export AGENT_ID=x` in one call, `alock acquire` in the next          | The lock is signed by the orchestrator and blocks no sibling |
+| Two sub-agents inventing the same obvious name                      | They count as one holder, and both get `ALREADY YOURS`       |
+| Skipping your own claim because the orchestrator "already holds it" | Two siblings edit one file and the last writer wins          |
+| Running `alock` from wherever the shell started                       | The lock lands in another repository                         |
+| Writing after a refusal                                             | The collision the lock existed to prevent                    |
+
+Needs `agent-lock` newer than 0.1.0 (`alock version`). Run `alock <command> --help` for flags.