@zalom/plastic 2.0.0-alpha.9 → 2.0.1

package/scripts/hook-stop

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# hook-stop (intent 340b, G7c, n4, D5): the Stop hook body. Reads the harness
+# payload from stdin, gathers the runtime config StopGate needs, and asks it
+# whether this session may stop. Prints Claude Code's Stop block schema on
+# stdout only when the answer is block; a permit prints nothing at all.
+# Registration is static (hooks/hooks.json, settings.json) - this launcher
+# always installs - and the decision is runtime, off by default
+# (runner.stop_hook defaults false), so the owner flips continuation on or
+# off by editing config with no reinstall. Every error permits: always
+# exits 0, never raises out to the harness.
+#
+# Usage: hook-stop <plastic_home>   (stdin: the hook JSON)
+
+require_relative "lib/store_layout"
+require "json"
+require_relative "lib/stop_gate"
+
+plastic_home = ARGV[0]
+exit 0 if plastic_home.nil? || plastic_home.empty?
+
+def read_config_value(key, home, read_config)
+  IO.popen({ "PLASTIC_HOME" => home }, [read_config, key], err: File::NULL, &:read).to_s.strip
+rescue StandardError
+  ""
+end
+
+begin
+  raw = $stdin.tty? ? "" : $stdin.read.to_s
+  payload = raw.strip.empty? ? {} : JSON.parse(raw)
+  payload = {} unless payload.is_a?(Hash)
+
+  home = File.expand_path(plastic_home)
+  global_store = Plastic::StoreLayout.global_store(home)
+  read_config = File.expand_path("read-config", __dir__)
+
+  config_stop_hook = read_config_value("runner.stop_hook", home, read_config)
+  roots_raw = read_config_value("project_roots", home, read_config)
+  project_roots =
+    begin
+      roots_raw.strip.empty? ? [] : Array(JSON.parse(roots_raw))
+    rescue JSON::ParserError
+      []
+    end
+  project_roots = project_roots.map { |root| File.expand_path(root.to_s) }
+
+  session = payload["session_id"].to_s
+
+  result = StopGate.decide(payload: payload, config_stop_hook: config_stop_hook, session: session,
+                           global_store: global_store, project_roots: project_roots)
+
+  puts JSON.generate("decision" => "block", "reason" => result[:reason]) if result[:block]
+rescue StandardError
+  nil
+end
+exit 0

package/scripts/index-projection

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# index-projection - the CLI over IndexProjection (intent 337, G4): prints
+# the drift between INDEX.md and the intent ledgers for one store root
+# (INDEX.md plus a store/ directory), exits non-zero when any drift exists.
+# --write renders INDEX.md's four status sections from the projection
+# through AtomicWrite; every other byte, including ## Clusters and
+# ## Relocated, is untouched.
+#
+# Usage:
+#   index-projection <store_root> [--write]
+#
+# Exit codes:
+#   0 - no drift (or, with --write, the write landed cleanly)
+#   1 - drift exists (a real terminal-ledger conflict, an INDEX entry with
+#       no directory, or a directory INDEX does not list)
+#   2 - usage: no argument, or the path is not a store root
+
+require_relative "lib/index_projection"
+
+module IndexProjectionCli
+  module_function
+
+  def usage
+    warn "Usage: index-projection <store_root> [--write]"
+  end
+
+  def main(argv)
+    args = argv.dup
+    write = !!args.delete("--write")
+
+    root = args.shift
+    unless root && Dir.exist?(root)
+      warn "index-projection: #{root.inspect} is not a store root"
+      usage
+      return 2
+    end
+
+    index_path = File.join(root, "INDEX.md")
+    store_dir = File.join(root, "store")
+    unless File.exist?(index_path)
+      warn "index-projection: no INDEX.md at #{index_path}"
+      return 2
+    end
+
+    if write
+      result = IndexProjection.write(store_dir, index_path: index_path)
+      unless result[:ok]
+        warn "index-projection: #{result[:error]}"
+        return 2
+      end
+      puts "index-projection: wrote #{index_path} (#{result[:moved].length} moved)"
+      return 0
+    end
+
+    analysis = IndexProjection.analyze(store_dir, index_path: index_path)
+    print_report(analysis)
+
+    (analysis[:drift].empty? && analysis[:index_only].empty? && analysis[:directory_only].empty?) ? 0 : 1
+  end
+
+  def print_report(analysis)
+    puts "Drift (#{analysis[:drift].length}):"
+    analysis[:drift].each { |r| puts "  #{r[:id]}: INDEX=#{r[:index_status]} ledger=#{r[:ledger_status]}" }
+    puts "INDEX-only (#{analysis[:index_only].length}):"
+    analysis[:index_only].each { |r| puts "  #{r[:id]} (#{r[:index_status]})" }
+    puts "Directory-only (#{analysis[:directory_only].length}):"
+    analysis[:directory_only].each { |r| puts "  #{r[:id]}" }
+  end
+end
+
+exit(IndexProjectionCli.main(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/insight-append

@@ -11,8 +11,15 @@
 # `now:` seam is the test seam; the CLI uses the default Time.now, which is fine
 # because determinism is covered at the library level (test/insights_test.rb).
 #
+# --rule (intent 341, G8, C37): tags the entry as a rule, not just an
+# observation, by prepending the literal "rule: " onto the text before it
+# ever reaches Insights.append_insight; the library itself stays untouched,
+# since a tag is a text-level convention, not a new field on the ledger.
+# Doctor's unpromoted_rules check (scripts/doctor.rb) later lists any tagged
+# entry whose exact text no docs/help/*.md chapter carries yet.
+#
 # Usage:
-#   insight-append <intent_dir> <text> --stage S --author A
+#   insight-append <intent_dir> <text> --stage S --author A [--rule]
 #
 # Exit codes: 0 (entry appended), 2 (usage).
 
@@ -21,6 +28,7 @@ require_relative "lib/insights"
 def parse_args(argv)
   stage = nil
   author = nil
+  rule = false
   positional = []
   i = 0
   while i < argv.length
@@ -31,21 +39,26 @@ def parse_args(argv)
     when "--author"
       author = argv[i + 1]
       i += 2
+    when "--rule"
+      rule = true
+      i += 1
     else
       positional << argv[i]
       i += 1
     end
   end
-  [positional[0], positional[1], stage, author]
+  [positional[0], positional[1], stage, author, rule]
 end
 
-intent_dir, text, stage, author = parse_args(ARGV)
+intent_dir, text, stage, author, rule = parse_args(ARGV)
 
 if [intent_dir, text, stage, author].any? { |v| v.nil? || v.to_s.empty? }
-  warn "usage: insight-append <intent_dir> <text> --stage S --author A"
+  warn "usage: insight-append <intent_dir> <text> --stage S --author A [--rule]"
   exit 2
 end
 
+text = "rule: #{text}" if rule
+
 entry = Insights.append_insight(File.expand_path(intent_dir), text,
                                 stage: stage, author: author)
 puts "appended: #{entry}"

package/scripts/install.rb

@@ -75,12 +75,15 @@ class Install < InstallerCore
   # they are reported, never re-installed, so the summary line and the Codex
   # trust reminder only ever count agents that actually changed this run.
   def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin,
-          already_registered: [])
+          already_registered: [], qmd_runner: QmdSync.default_runner, qmd_detector: QmdSync.method(:detect))
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
     distribute(mode)
     bootstrap if fresh
+    git_init_if_absent
+    register_with_qmd(runner: qmd_runner, detector: qmd_detector)
+    migrate_advisor_config_file(File.join(plastic_home, "config.yml"))
     apply_config_flags(argv)
 
     results = selected.map do |key|
@@ -135,13 +138,13 @@ class Install < InstallerCore
   end
 
   def git_probe
-    !`command -v git`.strip.empty?
+    !`git --version`.strip.empty?
   rescue StandardError
     false
   end
 
   def mise_probe
-    !`command -v mise`.strip.empty?
+    !`mise --version`.strip.empty?
   rescue StandardError
     false
   end
@@ -239,10 +242,9 @@ class Install < InstallerCore
         --no-advisor         Skip installing both advisor agents and the agent-advisor
                              skill (advisor.enabled: false)
         --advisor VALUE      Which advisor agent is the default: an agent name, or the
-                             shorthand "real" (plastic-advisor) or "faux"
-                             (plastic-faux-advisor). Writes advisor.claude.default. Left
-                             unset, the agent-advisor skill falls back to
-                             plastic-faux-advisor at consult time.
+                             shorthand "primary" or "secondary". Legacy "real" and
+                             "faux" aliases remain accepted. Writes advisor.claude.default.
+                             Left unset, the agent-advisor skill falls back to Primary Advisor.
         -h, --help           Show this help
 
       Notes:

package/scripts/lib/action_graph_shim.rb

@@ -0,0 +1,279 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_file"
+require_relative "savepoint"
+require_relative "work_graph_validator"
+
+# ActionGraphShim (intent 342, G9): a read-time backward shim that presents
+# any intent directory's actions/*.md as a node graph, in the record shape
+# NodeFile.parse returns, so 336, 338 and 339 read a legacy intent through
+# the same call they already use for an authored graph.md (spec.md D1-D18).
+#
+# Writes nothing, anywhere, ever (D1). An authored graph.md always wins over
+# the synthetic chain (D3) - the reverse of 334's forward shim, which
+# resolves content and prefers the older, richer source. This one resolves
+# structure, where an authored graph is the only real graph.
+module ActionGraphShim
+  module_function
+
+  # D10's heading test: unchanged, four tokens, verified correct on the live
+  # store. Governs only whether a "## Files ..." heading itself is negated
+  # (e.g. "## Files you must NOT change"), never the section body.
+  FILES_NEGATION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't/i.freeze
+
+  # D19's body-truncation vocabulary: the four heading tokens plus the
+  # exclusion phrases the live corpus actually uses ("Out of bounds, owned
+  # by leads running in parallel right now:" matched none of the original
+  # four). Governs whether a body LINE truncates the files harvest -
+  # never the heading test above, which stays on FILES_NEGATION_RE.
+  FILES_EXCLUSION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't|\bout of bounds\b|\bout of scope\b|\bhands off\b|\bleave alone\b|\bexcluded\b/i.freeze
+
+  BACKTICK_RE = /`([^`]+)`/.freeze
+  PROVEN_BY_LABEL_RE = /\AS\d+\z/.freeze
+
+  # :authored when graph.md exists, :actions when it does not but the intent
+  # holds at least one real action file (D7's exact realness test, reused
+  # rather than reimplemented so the shim can never disagree with
+  # Savepoint.has_real_action? about whether an intent has work in it), :none
+  # otherwise. A directory that does not exist returns :none and never
+  # raises.
+  def shape(intent_dir)
+    return :none unless intent_dir && File.directory?(intent_dir.to_s)
+    return :authored if File.exist?(File.join(intent_dir, "graph.md"))
+    return :actions if Savepoint.has_real_files_in?("actions", intent_dir)
+
+    :none
+  end
+
+  # The seven-key hash GraphFile.parse returns (ok:, goal:, decisions:,
+  # graph:, status:, verify:, errors:), for whichever shape the directory
+  # is in. On :authored this is literally GraphFile.parse, unmodified (D3).
+  # On :actions the same hash is built from the action files, with goal:,
+  # decisions: and status: nil (a 2024 action file was never asked for
+  # them) and verify: a fixed reason so a trivial-bar check the caller may
+  # run stays self-consistent. On :none it is GraphFile.parse's own
+  # not-found failure, produced by delegating to it rather than
+  # reformatting the message ourselves.
+  def view(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    when :actions
+      synth = synthetic_graph(intent_dir)
+      {
+        ok: synth[:errors].empty?,
+        goal: nil,
+        decisions: nil,
+        graph: synth,
+        status: nil,
+        verify: { reason: "backward shim: legacy actions/ carry no verify node" },
+        errors: synth[:errors],
+      }
+    else
+      # 342 post-execution review, should-fix 5: a nil intent_dir must never
+      # raise. shape(nil) is already nil-guarded, so `view` and `needs`
+      # honor the same contract rather than raising a File.join TypeError.
+      return GraphFile.failure(["graph file not found: #{intent_dir.inspect}"]) unless intent_dir
+
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    end
+  end
+
+  # Node records for either shape (D8), always carrying NodeFile.parse's own
+  # key set (ok:, node:, kind:, files:, budget:, report:, body:, errors:) plus
+  # needs:, path: and proven_by:. [] on :none, never a raise on a real
+  # directory.
+  def nodes(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      authored_nodes(intent_dir)
+    when :actions
+      synthetic_nodes(intent_dir)
+    else
+      []
+    end
+  end
+
+  # The needs targets for one node id, under either shape; [] for an id the
+  # graph does not declare, and [] for a directory with no graph at all.
+  def needs(intent_dir, node_id)
+    graph = view(intent_dir)[:graph]
+    return [] unless graph
+
+    (graph[:edges] || {})[node_id] || []
+  end
+
+  # --- authored shape -------------------------------------------------------
+
+  def authored_nodes(intent_dir)
+    parsed = GraphFile.parse(File.join(intent_dir, "graph.md"))
+    edges = parsed.dig(:graph, :edges) || {}
+
+    # 342 post-execution review, nit 8: sort_key numerically over the
+    # basename, the same key the synthetic chain uses, so an authored
+    # intent with ten or more nodes orders n10 after n9 rather than
+    # lexically between n1 and n2.
+    Dir.glob(File.join(intent_dir, "nodes", "*.md"))
+       .sort_by { |path| sort_key(File.basename(path)) }
+       .map do |path|
+      nf = NodeFile.parse(path)
+      nf.merge(
+        needs: edges[nf[:node]] || [],
+        path: path,
+        proven_by: proven_by_labels(nf[:body].to_s)
+      )
+    end
+  end
+
+  # --- actions shape ----------------------------------------------------------
+
+  # {nodes:, edges:, errors:} built directly over the minted chain, in the
+  # same shape GraphEdges.parse returns, rather than rendering a "## Graph"
+  # section and reparsing it.
+  def synthetic_graph(intent_dir)
+    ids = real_action_files(intent_dir).each_index.map { |i| "n#{i + 1}" }
+    edges = {}
+    ids.each_with_index { |id, i| edges[id] = i.zero? ? [] : [ids[i - 1]] }
+    { nodes: ids, edges: edges, errors: [] }
+  end
+
+  def synthetic_nodes(intent_dir)
+    files = real_action_files(intent_dir)
+    files.each_with_index.map do |path, i|
+      id = "n#{i + 1}"
+      needs_targets = i.zero? ? [] : ["n#{i}"]
+      begin
+        text = File.read(path)
+        {
+          ok: true,
+          node: id,
+          kind: "work",
+          files: files_section_paths(text),
+          budget: nil,
+          report: nil,
+          body: text,
+          errors: [],
+          needs: needs_targets,
+          path: path,
+          proven_by: proven_by_labels(text),
+        }
+      rescue StandardError => e
+        {
+          ok: false,
+          node: id,
+          kind: "work",
+          files: [],
+          budget: nil,
+          report: nil,
+          body: nil,
+          errors: ["could not read #{path}: #{e.message}"],
+          needs: needs_targets,
+          path: path,
+          proven_by: [],
+        }
+      end
+    end
+  end
+
+  # Real action files (File.file?, non-zero size, Savepoint.stage_file_present?
+  # - D7's own three-part predicate, applied per file since has_real_files_in?
+  # only answers true/false), ordered by the integer trailing the basename,
+  # falling back to the basename itself so the key is a total order over
+  # every basename shape the live store holds (D4).
+  def real_action_files(intent_dir)
+    Dir.glob(File.join(intent_dir.to_s, "actions", "*.md"))
+       .select { |f| File.file?(f) && File.size(f) > 0 && Savepoint.stage_file_present?(f) }
+       .sort_by { |f| sort_key(File.basename(f)) }
+  end
+
+  def sort_key(basename)
+    m = basename.match(/\d+/)
+    m ? [0, m[0].to_i, basename] : [1, 0, basename]
+  end
+
+  # The first heading whose leading token is "Files" (case-insensitively),
+  # unless the heading text carries a negation, in which case it is not a
+  # files section and the search continues (D10). Paths come out of that
+  # section's BODY through extract_files_paths, which is itself
+  # negation-aware and fence-aware (D17, D18). No qualifying heading gives
+  # [] (D9).
+  def files_section_paths(text)
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless files_heading?(heading)
+
+      return extract_files_paths(section.to_s)
+    end
+    []
+  end
+
+  # Fence-aware (D18) and negation-aware over the section body, not only
+  # its heading (D17). D10 already stops a heading like "## Files you must
+  # NOT change" from being read as a files section at all; this handles
+  # the equally common case where a legitimate "## Files to touch" heading
+  # is followed, inside the same section, by an out-of-bounds paragraph -
+  # live on this intent's own dogfood fixture. A fenced block is dropped
+  # before anything else runs, reusing NodeFile.each_fence_line rather than
+  # a bare backtick scan, which is exactly what that helper exists to
+  # prevent.
+  #
+  # Lines are scanned in document order; harvesting stops at the first line
+  # an exclusion GOVERNS (D19), not merely mentions - a negation is a false
+  # positive as often as a real exclusion clause, since an action file
+  # routinely annotates an in-bounds path with a "do NOT rename it" aside.
+  # governs_exclusion? draws the line: the match governs when it begins
+  # before the line's first backtick (an exclusion clause introducing
+  # paths) or when the line carries no backtick at all (a bare warning
+  # sentence); it annotates, and the line is kept, when the match falls
+  # after the first backtick (a parenthetical about a path already named).
+  # Any span that still holds a newline is rejected as a backstop: a path
+  # is never more than one line.
+  def extract_files_paths(section)
+    kept = +""
+    NodeFile.each_fence_line(section) do |line, fenced|
+      next if fenced
+      break if governs_exclusion?(line)
+
+      kept << line
+    end
+    kept.scan(BACKTICK_RE).flatten.reject { |s| s.include?("\n") }.uniq
+  end
+
+  # True when a FILES_EXCLUSION_RE match on this line governs the paths on
+  # it rather than merely annotating one (D19).
+  def governs_exclusion?(line)
+    match = line.match(FILES_EXCLUSION_RE)
+    return false unless match
+
+    first_backtick = line.index("`")
+    first_backtick.nil? || match.begin(0) < first_backtick
+  end
+
+  def files_heading?(heading)
+    stripped = heading.to_s.sub(/\A#+\s*/, "")
+    first_token = stripped.split(/\s+/, 2).first.to_s.sub(/[^A-Za-z]+\z/, "")
+    return false unless first_token.casecmp?("Files")
+
+    !heading.to_s.match?(FILES_NEGATION_RE)
+  end
+
+  # The S\d+ tokens of a file's headings, in heading order, taking a
+  # heading only when it owns at least one table data row (D5) - the same
+  # table-owning rule WorkGraphValidator.has_valid_matrix? and ReportScreen
+  # already apply, reused unmodified rather than adapted, so a prose
+  # mention of an S-label never manufactures a Proven-by source (334's
+  # post-execution review defect, in the other direction).
+  def proven_by_labels(text)
+    labels = []
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless NodeFile.table_rows(section).any?
+
+      WorkGraphValidator.heading_tokens(heading).each do |token|
+        labels << token if token.match?(PROVEN_BY_LABEL_RE)
+      end
+    end
+    labels
+  end
+end

package/scripts/lib/active_delivery.rb

@@ -0,0 +1,105 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "lock"
+
+# ActiveDelivery (intent 340b, G7c, n4, D10): which intent a session is
+# delivering. A lock is a file inside an intent directory, and intents live
+# under the global store or under any configured project's store, so
+# answering "which intent" needs a walk, not an index the way node_ids.rb
+# indexes ids: one Dir.glob per configured root (plus one for the global
+# store) and one JSON parse per candidate lock file. No validator, no graph
+# rebuild, nothing else touches disk. Shared by StopGate (the fourth arming
+# condition needs to know the lock's run_mode) and Handoff (the Runner
+# section needs to know which intent's runner-step.last to render).
+#
+# Pure and dependency-injected: every call takes explicit paths; nothing
+# here reads ENV, shells out, or raises across its own boundary.
+module ActiveDelivery
+  module_function
+
+  # resolve(global_store:, project_roots:, session:, ttl:, now:) -> intent_dir or nil.
+  # Nil for zero matches or more than one: a session holding two live locks
+  # at once is a state nothing downstream may guess through (row 4.25).
+  def resolve(global_store:, project_roots:, session:, ttl: Lock::TTL_SECONDS, now: Time.now)
+    held = candidate_intent_dirs(global_store: global_store, project_roots: project_roots)
+           .uniq
+           .select { |dir| held_live?(dir, session: session, ttl: ttl, now: now) }
+    held.size == 1 ? held.first : nil
+  end
+
+  # Every intent directory under the global store or a configured project
+  # root that carries a delivery.lock file, unparsed. One Dir.glob per root
+  # (row 4.27): the global store's intents sit directly under store/, a
+  # project root's intents sit two levels down, under <root>/<slug>/store/.
+  def candidate_intent_dirs(global_store:, project_roots:)
+    dirs = []
+    dirs.concat(Dir.glob(File.join(global_store.to_s, "*", "delivery.lock"))) unless blank?(global_store)
+    Array(project_roots).each do |root|
+      next if blank?(root)
+
+      dirs.concat(Dir.glob(File.join(root.to_s, "*", "store", "*", "delivery.lock")))
+    end
+    dirs.map { |lock_path| File.dirname(lock_path) }
+  end
+
+  # Live and held by this session: a fresh (non-expired) lock whose owner or
+  # delegate list names this session. A torn or unparseable lock is skipped,
+  # never raised (row 4.26): a module a hook depends on must fail as quietly
+  # as the hook itself does.
+  def held_live?(intent_dir, session:, ttl:, now:)
+    return false unless Lock.fresh?(intent_dir, ttl: ttl, now: now)
+
+    Lock.holds?(intent_dir, session: session)
+  rescue StandardError
+    false
+  end
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  DEFAULT_PROJECT_ROOTS = ["~/.plastic/projects", "~/.plastic/stores"].freeze
+
+  # The configured project roots (344 n2, D6): the `project_roots` list in
+  # `<plastic_home>/config.yml`, each expanded, or the default
+  # `~/.plastic/projects` when the key is absent or the file cannot be read
+  # or parsed. Never raises: a broken config.yml must never crash a hook on
+  # every prompt.
+  def project_roots(plastic_home)
+    path = File.join(plastic_home.to_s, "config.yml")
+    data = File.exist?(path) ? YAML.safe_load(File.read(path)) : nil
+    roots = data.is_a?(Hash) ? data["project_roots"] : nil
+    roots = DEFAULT_PROJECT_ROOTS unless roots.is_a?(Array) && !roots.empty?
+    roots.map { |root| File.expand_path(root.to_s) }
+  rescue StandardError
+    DEFAULT_PROJECT_ROOTS.map { |root| File.expand_path(root) }
+  end
+
+  # resolve_by_short_session(...) -> intent_dir or nil (344 n2). The tmp dir
+  # name is the short session id, while lock owners and delegates carry full
+  # ids, so this matches a lock whose owner or a delegate session STARTS WITH
+  # the short id. Nil for zero or more than one match, mirroring resolve's
+  # own uniqueness rule: an ambiguous short id names nothing downstream may
+  # guess through.
+  def resolve_by_short_session(global_store:, project_roots:, short_session:,
+                               ttl: Lock::TTL_SECONDS, now: Time.now)
+    held = candidate_intent_dirs(global_store: global_store, project_roots: project_roots)
+           .uniq
+           .select { |dir| held_live_by_short?(dir, short_session: short_session, ttl: ttl, now: now) }
+    held.size == 1 ? held.first : nil
+  end
+
+  def held_live_by_short?(intent_dir, short_session:, ttl:, now:)
+    return false unless Lock.fresh?(intent_dir, ttl: ttl, now: now)
+
+    data = Lock.read(intent_dir)
+    return false unless data.is_a?(Hash)
+
+    sessions = [data["owner_session"]] + Array(data["delegates"])
+    sessions.compact.map(&:to_s).any? { |session| session.start_with?(short_session.to_s) }
+  rescue StandardError
+    false
+  end
+end