agent-lock 0.2.1

data/lib/agent/lock/cli/commands/release_all.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # What a session should run when it finishes, so the next one does not
+        # have to work out whether it crashed.
+        class ReleaseAll < Base
+          desc "Release every lock this session holds"
+
+          def call(**options)
+            result = manager(options[:dir]).release_all
+            result.records.each { |record| say("RELEASED #{record.scope}") }
+            say("Released #{result.records.size} lock(s).")
+            finish(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/resume.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Pick up work a reboot or a crash interrupted.
+        #
+        # A lock whose holder died is orphaned rather than deleted when it has
+        # notes in it. This takes it back, prints what the last session wrote,
+        # and makes it a live claim again under the current identity.
+        class Resume < Base
+          desc "Take back a lock a crash or a reboot interrupted"
+
+          argument :scope, required: true, desc: "The path or glob to pick up"
+
+          def call(scope:, **options)
+            result = manager(options[:dir]).resume(scope)
+
+            if result.status == :not_found
+              say("NOTHING TO RESUME #{scope}")
+            else
+              say("RESUMED #{result.record.scope}  (holder: #{result.record.agent_id})")
+              say("")
+              say(result.record.intent)
+            end
+
+            finish(result)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/skill.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../../skill"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Where the bundled skill is, for a harness that would rather link it
+        # than copy it, or a configuration that names it by path.
+        class SkillPath < Base
+          desc "Print the directory of the skill this gem ships"
+
+          def call(**)
+            say(Skill.source)
+          end
+        end
+
+        # Copy the bundled skill into a skills directory, so an agent learns
+        # how to claim files before it first needs to.
+        class SkillInstall < Base
+          desc "Copy the skill this gem ships into a skills directory"
+
+          option :into, type: :string, default: nil, aliases: ["-o"],
+                        desc: "The skills directory, default ~/.agents/skills"
+          option :for, type: :string, default: nil, aliases: ["-a"],
+                       desc: "AI coding agent name, eg 'codex', or 'claude'"
+          option :force, type: :boolean, default: false, aliases: ["-f"],
+                         desc: "Replace a copy that differs from this one"
+
+          example ["", "--into ~/.claude/skills", "--force"]
+          example ["", "--for claude"]
+
+          # @param options [Hash]
+          def call(**options)
+            into = destination_for(options)
+            skill = into ? Skill.new(into: into) : Skill.new
+
+            result = skill.install(force: options[:force])
+            report(result)
+            finish(result)
+          end
+
+          private
+
+          # @param options [Hash]
+          # @return [String, nil] where to install, or nil for Skill's own default
+          def destination_for(options)
+            return options[:into] unless options[:for]
+
+            warn_("Both --for and --into options are provided; --for will be ignored") if options[:into]
+            return options[:into] if options[:into]
+
+            agent_dir = options[:for] == "claude" ? ".claude" : ".agents"
+            File.join(Dir.home, agent_dir, "skills")
+          end
+
+          # @param result [Skill::Result]
+          def report(result)
+            case result.status
+            when :installed then say("INSTALLED #{result.path}")
+            when :current then say("UP TO DATE #{result.path}")
+            when :differs
+              warn_("REFUSED: #{result.path} differs from the copy this gem ships")
+              warn_("  #{program} skill install --force   # replace it")
+            when :linked
+              warn_("REFUSED: #{result.path} is a symlink, so something else installs it; left alone")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/version.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # What is installed, for a bug report.
+        class Version < Base
+          desc "Print the version"
+
+          def call(**)
+            say(Agent::Lock::VERSION)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli/commands/whoami.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../../identity"
+
+module Agent
+  module Lock
+    module CLI
+      module Commands
+        # Who a lock taken from here would say holds it, and who its parent is.
+        #
+        # A sub-agent runs inside its parent's process, so nothing but the
+        # AGENT_ID it was told to use tells the two apart. A typo or a missing
+        # export puts its locks down under somebody else's name, where they
+        # block no sibling, and nothing says so. This is the check to run
+        # before the first claim: `AGENT_ID=rey-frontend alock whoami`.
+        #
+        # It reads the environment and nothing else. No tree and no store, so
+        # asking the question can neither fail outside a checkout nor leave a
+        # store behind in one.
+        class Whoami < Base
+          # Where #id came from, worded for a human. The keys are Identity's
+          # own symbols, which are what --json reports.
+          SOURCES = {
+            explicit: "from AGENT_ID",
+            session: "from CLAUDE_SESSION_ID",
+            fingerprint: "from the process fingerprint"
+          }.freeze
+
+          # Where #parent_id came from, likewise.
+          PARENT_SOURCES = {
+            explicit: "from AGENT_PARENT_ID",
+            inferred: "inferred: the session this runs in, since AGENT_ID names somebody else"
+          }.freeze
+
+          desc "Say who a lock taken now would be held by, and where that came from"
+
+          option :json, type: :boolean, default: false, desc: "Machine-readable output"
+
+          example ["", "--json"]
+
+          # @param options [Hash]
+          def call(**options)
+            identity = Identity.current
+            warn_shared(identity) unless identity.source == :explicit
+            return say(JSON.pretty_generate(as_hash(identity))) if options[:json]
+
+            say("id:     #{identity.id}  (#{SOURCES.fetch(identity.source)})")
+            say(parent_line(identity))
+          end
+
+          private
+
+          # @param identity [Identity]
+          # @return [String]
+          def parent_line(identity)
+            return "parent: none" if identity.parent_id.nil?
+
+            "parent: #{identity.parent_id}  (#{PARENT_SOURCES.fetch(identity.parent_source)})"
+          end
+
+          # The failure this command exists to catch. Without AGENT_ID, every
+          # sub-agent of this session inherits the same environment and runs
+          # in the same process, so each resolves to this same id and none of
+          # them can ever block another.
+          #
+          # @param identity [Identity]
+          def warn_shared(identity)
+            warn_("note: every sub-agent of this session answers to #{identity.id} too, so none can block another.")
+            warn_("      Give each one its own: AGENT_ID=<name> #{program} acquire ...")
+          end
+
+          # @param identity [Identity]
+          # @return [Hash]
+          def as_hash(identity)
+            { id: identity.id, source: identity.source,
+              parent_id: identity.parent_id, parent_source: identity.parent_source }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/lock/cli.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "manager"
+require "dry/cli"
+
+module Agent
+  module Lock
+    # The command line, and nothing else. Every command here is a thin shell:
+    # parse flags, call one Manager method, print the result, set an exit code.
+    # No command decides anything a library object could decide instead.
+    module CLI
+      # What the gem is installed as. Taken from the gemspec's one executable
+      # rather than from $PROGRAM_NAME, which under a test runner is the
+      # runner. The completion script it emits names the program in every
+      # line, so guessing it wrong is not a cosmetic mistake.
+      PROGRAM_NAME = "alock"
+
+      # A registry whose commands are already bound to this launcher, so a
+      # command writes to the streams it was given rather than to the process's.
+      #
+      # @param launcher [Launcher]
+      # @return [Dry::CLI::Registry]
+      def self.registry_for(launcher)
+        # `extend` and `register` have to be sent to the new class explicitly.
+        # Inside a `tap` block `self` is still this module, so writing them
+        # bare turned Agent::Lock::CLI itself into the registry, handed back a
+        # class that knew no commands, and left the completion command bound
+        # to that empty class.
+        registry = Class.new { extend Dry::CLI::Registry }
+
+        COMMANDS.each do |name, (klass, aliases)|
+          registry.register(name, klass.new(launcher), aliases: aliases)
+        end
+
+        registry.register("completion", Commands::Completion[registry, program_name: PROGRAM_NAME])
+        registry
+      end
+
+      # The whole command line, in one place, so adding a verb is one line
+      # rather than three. Filled in below, once the commands are loaded.
+    end
+  end
+end
+
+require_relative "cli/commands/base"
+require_relative "cli/commands/acquire"
+require_relative "cli/commands/release"
+require_relative "cli/commands/check"
+require_relative "cli/commands/list"
+require_relative "cli/commands/mine"
+require_relative "cli/commands/release_all"
+require_relative "cli/commands/break"
+require_relative "cli/commands/note"
+require_relative "cli/commands/resume"
+require_relative "cli/commands/whoami"
+require_relative "cli/commands/skill"
+require_relative "cli/commands/version"
+require_relative "cli/commands/completion"
+
+module Agent
+  module Lock
+    module CLI
+      COMMANDS = {
+        "acquire" => [Commands::Acquire, []],
+        "release" => [Commands::Release, []],
+        "check" => [Commands::Check, []],
+        "list" => [Commands::List, ["ls"]],
+        "mine" => [Commands::Mine, []],
+        "release-all" => [Commands::ReleaseAll, []],
+        "break" => [Commands::Break, []],
+        "note" => [Commands::Note, []],
+        "resume" => [Commands::Resume, []],
+        "whoami" => [Commands::Whoami, []],
+        "skill path" => [Commands::SkillPath, []],
+        "skill install" => [Commands::SkillInstall, []],
+        "version" => [Commands::Version, %w[-v --version]]
+      }.freeze
+    end
+  end
+end

data/lib/agent/lock/error.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Agent
+  module Lock
+    # The base of everything this gem raises. In a file of its own so that any
+    # part of the library can require it without reaching for the entry point,
+    # which would require the part doing the asking.
+    class Error < StandardError; end
+  end
+end

data/lib/agent/lock/freeze.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Agent
+  module Lock
+    # Optional teeth, for the scope you want nobody to touch at all.
+    #
+    # An advisory lock works because every agent checks it. That covers the
+    # agents that check. `chflags uchg` on macOS makes the file unwritable by
+    # anything, checking or not, which is the right answer for a handful of
+    # files that must not move while something else runs.
+    #
+    # It is opt-in for three reasons. It is macOS only, since Linux's `chattr
+    # +i` needs root. It denies the holder too, so it fits a freeze rather than
+    # a file you are editing. And a session that dies with files frozen leaves
+    # a tree where `git checkout` and `rm -rf` fail with "Operation not
+    # permitted", which is why every frozen path is written into the lock: the
+    # thaw does not depend on the process that froze them still being alive.
+    module Freeze
+      # A freeze walks and flags every matched file, so a scope covering a
+      # whole checkout is a mistake rather than an instruction.
+      LIMIT = 500
+
+      # How many paths one `chflags` invocation is given.
+      BATCH = 200
+
+      class TooBroad < Error; end
+
+      module_function
+
+      # @return [Boolean]
+      def supported? = RUBY_PLATFORM.include?("darwin")
+
+      # @param scope [Scope]
+      # @param tree [Tree]
+      # @return [Array<String>] the files it would freeze, relative to the root
+      def matches(scope, tree)
+        Dir.glob(recursive(scope.pattern), base: tree.root, flags: File::FNM_EXTGLOB)
+           .select { |rel| File.file?(File.join(tree.root, rel)) }
+           .reject { |rel| rel.start_with?(".git/") }
+           .sort
+      end
+
+      # A trailing `**` means "everything under here" to this gem, and to
+      # anybody typing it. It does not mean that to Dir.glob, where a bare
+      # `**` at the end matches one level, exactly like `*`. Only `**/` walks
+      # down. So a scope that covers a subtree is spelled out before globbing.
+      #
+      # @param pattern [String]
+      # @return [String]
+      def recursive(pattern) = pattern.end_with?("**") ? "#{pattern}/*" : pattern
+
+      # @param paths [Array<String>] relative to the tree root
+      # @param tree [Tree]
+      # @param force [Boolean] allow a freeze wider than LIMIT
+      # @return [Array<String>] what was frozen
+      def apply(paths, tree:, force: false)
+        raise TooBroad, "--enforce needs macOS; this is #{RUBY_PLATFORM}" unless supported?
+        return [] if paths.empty?
+        raise TooBroad, "#{paths.size} files is wider than a freeze should be" if paths.size > LIMIT && !force
+
+        chflags("uchg", paths, tree)
+      end
+
+      # Best effort on purpose: a path that has since been deleted or already
+      # thawed is not a reason to leave the rest frozen.
+      #
+      # @return [Array<String>] what was thawed
+      def clear(paths, tree:)
+        return [] if paths.nil? || paths.empty?
+
+        chflags("nouchg", paths, tree)
+      end
+
+      # Only the files `chflags` actually accepted come back.
+      #
+      # A batch that fails is retried one file at a time, because the usual
+      # reason is a single path somebody else owns, and reporting the whole
+      # batch as frozen would leave the lock claiming protection it does not
+      # have. Reporting the whole batch as failed would be just as wrong.
+      #
+      # @return [Array<String>] relative paths that are now flagged
+      def chflags(flag, paths, tree)
+        return [] unless supported?
+
+        paths.each_slice(BATCH)
+             .flat_map { |batch| flag_batch(flag, existing(batch, tree)) }
+             .map { |path| path.delete_prefix("#{tree.root}/") }
+      end
+
+      # @return [Array<String>] absolute paths that are still there to flag
+      def existing(batch, tree)
+        batch.map { |rel| File.join(tree.root, rel) }.select { |path| File.exist?(path) }
+      end
+
+      # @return [Array<String>] the ones the command accepted
+      def flag_batch(flag, absolute)
+        return [] if absolute.empty?
+        return absolute if run(flag, absolute)
+
+        absolute.select { |path| run(flag, [path]) }
+      end
+
+      # @return [Boolean] whether the command reported success
+      def run(flag, paths) = system("chflags", flag, *paths, out: File::NULL, err: File::NULL) || false
+    end
+  end
+end

data/lib/agent/lock/identity.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "etc"
+require "socket"
+require "digest"
+
+module Agent
+  module Lock
+    # Who is asking, and whether they are still around.
+    #
+    # A lock is worthless unless the holder gives the same answer every time it
+    # is asked. The obvious answer, this process's own pid, is the wrong one: an
+    # agent harness runs each command in a shell of its own, so a lock acquired
+    # by one invocation could never be released by the next. The identity has to
+    # belong to the session, not to the process that happens to be speaking for
+    # it right now.
+    #
+    # In order of preference:
+    #
+    #   AGENT_ID             what a human or a harness set on purpose
+    #   CLAUDE_SESSION_ID    the session, which survives --resume
+    #   fingerprint          the first ancestor process that is not a shell
+    #
+    # The fingerprint is the fallback that needs explaining. Walking up from
+    # this process, the shells are throwaway and the thing above them is not:
+    # the `claude` or `codex` process driving the session, or the terminal a
+    # human is typing in. Its pid and start time, hashed, are stable for as
+    # long as that session lives and different for anybody else's.
+    class Identity
+      SHELLS = %w[sh bash zsh ksh csh tcsh fish dash].freeze
+      MAX_HOPS = 10
+
+      class << self
+        # Deliberately not memoized. A forked CLI computes this once and dies,
+        # but the same code runs inside a long-lived process during the specs
+        # and inside any harness that loads the library, where a cached answer
+        # would outlive the environment it was computed from.
+        #
+        # @return [Identity]
+        def current = new
+
+        # The ancestry walk, on the other hand, cannot change while this
+        # process lives, and it costs two `ps` calls per hop.
+        #
+        # @return [Integer]
+        def session_pid = @session_pid ||= yield
+      end
+
+      # @param env [Hash]
+      def initialize(env: ENV)
+        @env = env
+      end
+
+      # @return [String] the holder name written into a lock
+      def id
+        @id ||= explicit || session || fingerprint
+      end
+
+      # The session that spawned this one: AGENT_PARENT_ID when a harness says
+      # so, and otherwise inferred.
+      #
+      # The inference exists because Claude Code runs a sub-agent inside its
+      # parent's own process and sets nothing to tell them apart, so without it
+      # every sub-agent resolved to its parent's fingerprint and none of them
+      # could ever block another. A sub-agent's one distinguishing mark is the
+      # AGENT_ID it was told to use. When that differs from what this session
+      # would answer to without it, the session is, by elimination, the
+      # parent.
+      #
+      # @return [String, nil]
+      def parent_id
+        return @parent_id if defined?(@parent_id)
+
+        @parent_id = declared_parent || inferred_parent
+      end
+
+      # Where #id came from, so a session can check what it is being taken for
+      # before a lock is written under the wrong name.
+      #
+      # @return [Symbol] :explicit, :session or :fingerprint
+      def source
+        return :explicit if explicit
+        return :session if session
+
+        :fingerprint
+      end
+
+      # Where #parent_id came from. An inferred parent is a guess a human may
+      # want to overrule with AGENT_PARENT_ID, so it is reported as one.
+      #
+      # @return [Symbol, nil] :explicit, :inferred, or nil when there is no parent
+      def parent_source
+        return :explicit if declared_parent
+
+        :inferred if parent_id
+      end
+
+      # Evidence, not identity: enough to ask later whether the holder is still
+      # running. The pid alone is not enough, since pids are reused, and the
+      # host matters because a lock store can be on a shared or synced volume.
+      #
+      # @return [Hash{Symbol => Object}]
+      def evidence
+        { pid: session_pid, started: ProcessInfo.started_at(session_pid), host: Socket.gethostname }
+      end
+
+      private
+
+      def explicit = presence(@env["AGENT_ID"])
+
+      def declared_parent = presence(@env["AGENT_PARENT_ID"])
+
+      # What this session answers to when nobody names it, which is the
+      # orchestrator's id. The session id counts as well as the fingerprint:
+      # under a harness that exports CLAUDE_SESSION_ID the orchestrator's locks
+      # carry that, and a parent inferred from the fingerprint alone would
+      # match none of them. A session that named itself by its own fingerprint
+      # is not its own child.
+      #
+      # @return [String, nil]
+      def inferred_parent
+        return nil unless explicit
+
+        own = session || fingerprint
+        own unless own == explicit
+      end
+
+      def session
+        value = presence(@env["CLAUDE_SESSION_ID"])
+        value && "session-#{value[0, 8]}"
+      end
+
+      # @return [String] e.g. "claude-1f4c8a02"
+      def fingerprint
+        pid = session_pid
+        name = ProcessInfo.command(pid) || "agent"
+        digest = Digest::SHA256.hexdigest(
+          [pid, ProcessInfo.started_at(pid), Etc.getpwuid(::Process.uid)&.name, Socket.gethostname].join("|")
+        )
+        "#{name}-#{digest[0, 8]}"
+      end
+
+      # The first ancestor that is not a shell, which is the process that lasts
+      # as long as the session does.
+      #
+      # @return [Integer]
+      def session_pid
+        self.class.session_pid do
+          pid = ::Process.ppid
+          MAX_HOPS.times do
+            name = ProcessInfo.command(pid)
+            break unless name && SHELLS.include?(name.delete_prefix("-"))
+
+            parent = ProcessInfo.parent_of(pid)
+            break unless parent && parent > 1
+
+            pid = parent
+          end
+          pid
+        end
+      end
+
+      def presence(value) = value.nil? || value.strip.empty? ? nil : value.strip
+    end
+  end
+end