@zalom/plastic 2.0.0-alpha.23 → 2.0.0-alpha.24

package/PLASTIC.md

@@ -83,14 +83,15 @@ runs the flow. A roadmap is an ordered, delivery-side collection; `plastic-roadm
   config.yml, projects.yml     # Preferences; slug -> path
   store/ID--slug/              # Strategic intents
   store/.sessions/<YYYYMMDD>/  # Day ledger: <YYYYMMDD>.md, checklist.md, savepoint.md
-  store/.tmp/<session>/        # current (the pointer), heartbeat; git-ignored
+  store/.tmp/<session>/        # heartbeat; git-ignored
 ~/.plastic/projects/{slug}/    # Project store: INDEX.md, AGENTS.md, roadmaps/, store/
 ```
 
-`<session>` is the first eight characters of the session id. The pointer holds a day id (the
-day ledger takes the record) or an intent id (an auto team owns the record); session start
-writes today's day id. The SessionStart hook picks the project store by matching the working
-directory against `projects.yml`; no Plastic files land in project code.
+`<session>` is the first eight characters of the session id. Session start writes the heartbeat
+file, proof only that the session started. The delivery lock (`delivery.lock` in the intent
+directory) names the session delivering an intent, as its owner or a delegate; with no lock a
+session records into its day ledger. SessionStart matches the working directory against
+`projects.yml` to pick the project store.
 
 Naming: intents are `ID--three-to-five-words`, the file matching the directory
 (`1a1--slug/1a1--slug.md`); next id: `ruby ~/.plastic/scripts/folgezettel-id <parent_id>

package/agents/plastic-node-research.md

@@ -2,7 +2,7 @@
 name: plastic-node-research
 description: |
   Dispatched for a research node by Plastic's node-graph runner. Given the
-  packet path the dispatch line names, research the question it names by
+  node input path the dispatch line names, research the question it names by
   reading the repository, and reply with the YAML return the dispatch line
   names. Read-only: no Bash, no edit. Never spawned outside a runner
   dispatch.
@@ -13,13 +13,13 @@ tools:
 model: sonnet
 ---
 
-You are one node in Plastic's node-graph runner: one packet in, one YAML return out, no diff.
+You are one node in Plastic's node-graph runner: one node input in, one YAML return out, no diff.
 
-Read the packet the dispatch line names; it is your whole input. Research the question it names
+Read the node input the dispatch line names; it is your whole input. Research the question it names
 by reading the repository, never by running it. This role carries no `Bash`, because Claude
 Code's `tools:` field grants or withholds a whole tool name, never a command pattern, and a shell
 is a write whatever command it runs. `Read`, `Glob`, and `Grep` are enough to read every file the
-packet points at.
+node input points at.
 
 A research node produces no diff. Put what you found in your return's `findings`, never in a code
 change.

package/agents/plastic-node-verify.md

@@ -2,7 +2,7 @@
 name: plastic-node-verify
 description: |
   Dispatched for a verify node by Plastic's node-graph runner. Given the
-  packet path the dispatch line names, check the work it names by reading
+  node input path the dispatch line names, check the work it names by reading
   the repository, and reply with the YAML return the dispatch line names.
   Read-only: no Bash, no edit. Never spawned outside a runner dispatch.
 tools:
@@ -12,13 +12,13 @@ tools:
 model: opus
 ---
 
-You are one node in Plastic's node-graph runner: one packet in, one YAML return out, no diff.
+You are one node in Plastic's node-graph runner: one node input in, one YAML return out, no diff.
 
-Read the packet the dispatch line names; it is your whole input. Verify what it asks you to
+Read the node input the dispatch line names; it is your whole input. Verify what it asks you to
 verify by reading the repository, never by running it. This role carries no `Bash`, because
 Claude Code's `tools:` field grants or withholds a whole tool name, never a command pattern, and
 a shell is a write whatever command it runs. `Read`, `Glob`, and `Grep` are enough to read every
-file the packet points at.
+file the node input points at.
 
 A verify node produces no diff. If verifying the work would require changing a file, that is not
 this role's job: say so in your return instead of reaching for a tool that could make the change.

package/agents/plastic-node-work.md

@@ -1,7 +1,7 @@
 ---
 name: plastic-node-work
 description: |
-  Dispatched for a work node by Plastic's node-graph runner. Given the packet
+  Dispatched for a work node by Plastic's node-graph runner. Given the node input
   path the dispatch line names, make the node's code changes inside the node
   worktree, commit them there, and reply with the YAML return the dispatch
   line names. Never spawned outside a runner dispatch.
@@ -15,11 +15,11 @@ tools:
 model: sonnet
 ---
 
-You are one node in Plastic's node-graph runner: one packet in, your files and your commit and
+You are one node in Plastic's node-graph runner: one node input in, your files and your commit and
 one YAML return out.
 
-Read the packet the dispatch line names; it is your whole input. Make the changes it asks for,
-inside the worktree it names, and commit them there. Touch no file outside the packet's `files:`
+Read the node input the dispatch line names; it is your whole input. Make the changes it asks for,
+inside the worktree it names, and commit them there. Touch no file outside the node input's `files:`
 list, write to no other node's worktree, and write no ledger line yourself: the runner's own
 gates read your commit and your return, never your word.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.23",
+  "version": "2.0.0-alpha.24",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/dashboard.rb

@@ -100,7 +100,7 @@ end
 # instead, with no end-of-line requirement, so trailing note prose is irrelevant. The
 # separator there may be a real em dash (U+2014, INDEX.md's normal on-write convention,
 # built from the codepoint so this source line stays em-dash free) or a plain hyphen
-# (end-intent's own Bridge.index_entry_match accepts either on read). Because regex
+# (end-intent's own IndexEntry.match accepts either on read). Because regex
 # alternation is leftmost-first, this only ever matches the date immediately after the
 # link. It never continues scanning into the note prose, so a second date mentioned
 # later in a note's free text cannot be mistaken for the completion date. The id class

package/scripts/end-intent

@@ -37,7 +37,7 @@
 #   2. Move the intent's INDEX.md line from `## Active` into `## Completed`
 #      (delivered) or `## Abandoned` (abandoned), dated today, appending
 #      --index-note (if given). Accepts a real em dash OR a plain hyphen as
-#      the id/title separator on READ (shared matcher, Bridge.index_entry_match);
+#      the id/title separator on READ (shared matcher, IndexEntry.match);
 #      always EMITS the real em dash on write. An id that resolves to neither
 #      `## Active` nor the terminal section is a loud failure (exit 1); an id
 #      already correctly in the terminal section is a quiet, idempotent success.
@@ -46,10 +46,9 @@
 #   5. Disarm (intent 188, D2/D16; intent 307): check the code worktree (derived
 #      from projects.yml and the intent id, Arm.worktree_block) for uncommitted
 #      changes first (exit 5 if dirty, unless --discard-worktree-changes); call the
-#      disarm seam (default Arm.disarm: worktree released, lock cleared, the session
-#      pointer back on the day ledger); verify the durable lock file is actually gone
-#      afterward, and release it directly when a foreign-keyed disarm left it (the
-#      /tmp bridge this step once read was removed in 2.0, intent 307).
+#      disarm seam (default Arm.disarm: worktree released, lock cleared); verify
+#      the durable lock file is actually gone afterward, and release it directly
+#      when a foreign-keyed disarm left it.
 #
 # Exit codes:
 #   0  ok - the intent is closed and no delivery.lock remains.
@@ -57,7 +56,7 @@
 #      nor the terminal section (D11). Deliberately double duty; see plan.md.
 #   2  retired in 2.0 (intent 308): the outcome.md guard reports and proceeds.
 #   3  steps 1-4 already committed, but the delivery lock genuinely could not
-#      be cleared (not a bridge cache miss; see step 5 above).
+#      be cleared (see step 5 above).
 #   4  pre-flight refusal: a FRESH foreign lock is held by a live,
 #      non-delegate session; a FRESH lock that will not parse (corrupt); or a
 #      lock file with no resolvable session identity at all. Authors nothing.
@@ -73,8 +72,8 @@ require "fileutils"
 require "date"
 require "open3"
 require "pathname"
-require_relative "lib/bridge"
 require_relative "lib/arm"
+require_relative "lib/index_entry"
 require_relative "lib/savepoint"
 require_relative "lib/lock"
 require_relative "lib/intent_validator"
@@ -89,7 +88,7 @@ DISPOSITIONS = %w[delivered abandoned].freeze
 # dash (U+2014), the existing INDEX.md convention (store files are exempt from
 # the no-em-dash shipped-file rule). Built from the codepoint, not a literal
 # byte in this source file, so the script's own source stays em-dash free.
-# READING accepts a plain hyphen too, via the shared Bridge.index_entry_match
+# READING accepts a plain hyphen too, via the shared IndexEntry.match
 # (intent 188, D9/D12): see move_index_to_terminal below.
 EM_DASH = "\u2014"
 
@@ -99,6 +98,10 @@ class UnresolvedIndexEntry < StandardError; end
 
 # --- Explicit flag parsing (no eval, no global injection) -------------------
 
+def blank?(value)
+  value.nil? || value.to_s.strip.empty?
+end
+
 def parse_args(argv)
   opts = {
     store: nil, id: nil, disposition: nil, index: nil,
@@ -438,10 +441,10 @@ def section_stop(lines, heading_idx)
   stop
 end
 
-# Shared matcher (Bridge.index_entry_match, intent 188 D12): accepts a real em
+# Shared matcher (IndexEntry.match, intent 188 D12): accepts a real em
 # dash OR a plain hyphen as the id/title separator on READ.
 def active_line_id(line)
-  m = Bridge.index_entry_match(line)
+  m = IndexEntry.match(line)
   m && m[1]
 end
 
@@ -520,7 +523,7 @@ def move_index_to_terminal(content, id, disposition, today:, index_note: nil)
     raise UnresolvedIndexEntry, "INDEX.md has no #{target_heading} heading; cannot complete the move"
   end
 
-  m = Bridge.index_entry_match(lines[entry_idx])
+  m = IndexEntry.match(lines[entry_idx])
   title, link = m[2], m[3]
   note_suffix = (index_note && !index_note.to_s.strip.empty?) ? " #{index_note.to_s.strip}" : ""
   new_entry = "- [#{id} #{EM_DASH} #{title}](#{link}) #{EM_DASH} #{today}#{note_suffix}\n"
@@ -609,13 +612,13 @@ end
 # exclusion with a raw backtrace. nil is the only safe "could not resolve"
 # signal; main refuses explicitly on it rather than ever reaching takeover.
 def resolve_end_session(explicit, intent_dir)
-  return explicit.to_s.strip unless Bridge.blank?(explicit)
+  return explicit.to_s.strip unless blank?(explicit)
   env = ENV["CLAUDE_CODE_SESSION_ID"]
-  return env.to_s.strip unless Bridge.blank?(env)
+  return env.to_s.strip unless blank?(env)
   lock = Lock.read(intent_dir)
   return nil unless lock
   owner = lock["owner_session"].to_s
-  Bridge.blank?(owner) ? nil : owner
+  blank?(owner) ? nil : owner
 end
 
 # Read-only pre-flight verdict (D4). Returns [:proceed, lock_or_nil],
@@ -663,7 +666,7 @@ end
 def run_disarm(intent_dir, id, session, discard_worktree_changes:,
                worktree_reader: ->(dir) { Arm.worktree_block(intent_dir: dir) },
                disarm: ->(sess, dir) { Arm.disarm(intent_dir: dir, session: sess) })
-  return :ok if Bridge.blank?(session)
+  return :ok if blank?(session)
 
   block = worktree_reader.call(intent_dir)
   worktree_code = block.is_a?(Hash) ? block["code"] : nil
@@ -788,7 +791,7 @@ def main(argv)
   # Lock.takeover (blank session reaches Lock.acquire's blank? guard AFTER the
   # existing lock file was already deleted) or silently mis-arbitrate. Refuse
   # rather than guess; nothing has been written yet.
-  if Bridge.blank?(session) && File.exist?(Lock.path(intent_dir))
+  if blank?(session) && File.exist?(Lock.path(intent_dir))
     warn "end-intent: a delivery lock exists at #{Lock.path(intent_dir)} but no session " \
          "identity could be resolved (--session, CLAUDE_CODE_SESSION_ID, and the lock's " \
          "own recorded owner are all blank); refusing rather than guessing. Pass " \

package/scripts/exec-worktree

@@ -21,15 +21,15 @@
 #      (--session, else CLAUDE_CODE_SESSION_ID, else the existing delivery.lock's own
 #      recorded owner_session when non-blank, else nil; the lock-owner fallback IS
 #      used here, matching end-intent's teardown resolution order).
-#      Derive the worktree block from projects.yml and the intent id (Arm.worktree_block;
-#      the /tmp bridge this once read was removed in 2.0, intent 307). No code worktree on
+#      Derive the worktree block from projects.yml and the intent id (Arm.worktree_block).
+#      No code worktree on
 #      disk means nothing was provisioned (exit 0).
 #   1. The dirty-worktree guard (delivered only): git status --porcelain on the code
 #      worktree. Not clean, or the check itself fails, fails CLOSED (exit 3), mirroring
 #      end-intent's dirty-worktree handling. abandoned skips this guard entirely: the
 #      branch survives and can be reclaimed, so a dirty worktree is not a reason to
 #      refuse.
-#   2. Finish: Worktree.finish(bridge_data, home:, runner:, merge: disposition ==
+#   2. Finish: Worktree.finish(delivery, home:, runner:, merge: disposition ==
 #      "delivered"). Worktree.finish is fail-open and never raises, so failure is
 #      detected by checking, for a delivered disposition only, whether the worktree
 #      directory still exists on disk afterward (release removes it on success).
@@ -38,8 +38,8 @@
 # one concern per script (spec D8).
 #
 # Exit codes:
-#   0  finished (merged or removed per disposition), or nothing to finish (no bridge
-#      resolved, or no code worktree recorded on the bridge)
+#   0  finished (merged or removed per disposition), or nothing to finish (no delivery
+#      resolved, or no code worktree recorded on it)
 #   1  usage or path-resolution failure
 #   2  retired in 2.0 (intent 302): was the order precondition; never emitted, never reused
 #   3  the worktree is not clean, or the merge/removal did not complete (delivered only)

package/scripts/hook-call-budget

@@ -21,10 +21,10 @@
 # transcript, at <dirname(transcript_path)>/<session_id>/subagents/
 # agent-<agent_id>.jsonl (the main transcript_path plus the main session_id
 # plus the subagent's own agent_id): its first user record carries the
-# dispatch prompt, and the lead/spawn block always pastes the node's packet
-# path into that prompt (PACKET_PATH_RE). The packet path names the intent
+# dispatch prompt, and the lead/spawn block always pastes the node's input
+# path into that prompt (INPUT_PATH_RE). The node input path names the intent
 # directory directly (its grandparent), so this hook never scans the store to
-# find it. No packet path in that first prompt means allow.
+# find it. No node input path in that first prompt means allow.
 #
 # The cap applies only when that node's LATEST transition line in
 # <intent>/savepoint.md is `running` and carries `calls=`; a later `done` or
@@ -47,10 +47,10 @@ module HookCallBudget
 
   RETURN_INSTRUCTION = "commit what is green and return failed_verification reason=call_budget"
 
-  # A node id, then "--a", then an attempt number, inside a /packets/
+  # A node id, then "--a", then an attempt number, inside a /attempts/
   # directory: the exact shape RunnerDispatch's spawn block pastes into a
   # subagent's own first prompt. Captures [full_path, node].
-  PACKET_PATH_RE = %r{(\S+/packets/([a-z]{1,2}\d+)--a\d+\.packet)}.freeze
+  INPUT_PATH_RE = %r{(\S+/attempts/([a-z]{1,2}\d+)--a\d+\.input)}.freeze
 
   FIRST_RECORD_SCAN_LIMIT = 20
 
@@ -78,7 +78,7 @@ module HookCallBudget
     end
     return nil unless prompt
 
-    match = PACKET_PATH_RE.match(prompt)
+    match = INPUT_PATH_RE.match(prompt)
     return nil unless match
 
     node = match[2]

package/scripts/hook-capture

@@ -15,6 +15,7 @@ require "time"
 require "fileutils"
 require_relative "lib/session_ledger"
 require_relative "lib/dashboard_banner"
+require_relative "lib/active_delivery"
 
 raw = begin
   $stdin.read
@@ -48,32 +49,31 @@ def truncate(text, max)
   "#{text[0, max - 3]}..."
 end
 
-# --- (a) tmp root + heartbeat, guarded on the pointer (spec D9) ------------
-# Session start writes the `current` pointer; a capture with no pointer yet
+# --- (a) heartbeat, guarded on the session tmp dir already existing --------
+# Session start creates `.tmp/<sid>/`; a capture with no such directory yet
 # means session start never ran for this session at all (a `-p` print
 # session, a resumed background job, an unregistered SessionStart hook), so
-# neither the per-session dir nor its heartbeat is created. UserPromptSubmit
-# fires before PostToolUse, so capture is the FIRST creator of every orphan
-# `.tmp/<sid>/` this guard prevents; hook-record carries the same guard for
-# its own (later) heartbeat write.
+# neither the directory nor its heartbeat is created HERE either.
+# UserPromptSubmit fires before PostToolUse, so capture is the FIRST place
+# this guard matters; hook-record carries the same guard for its own
+# (later) heartbeat write. (344 n2, D4-D5)
 begin
-  if File.exist?(SessionLedger.pointer_path(store, sid))
-    SessionLedger.ensure_tmp_root(store)
-    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+  if Dir.exist?(SessionLedger.session_tmp_dir(store, sid))
     File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
   end
 rescue StandardError
   nil
 end
 
-# --- (b) read the pointer -----------------------------------------------
+# --- (b) a live delivery lock names this session (344 n2, D5, D12) ----------
 skip_day_ledger = false
 begin
-  pointer = SessionLedger.pointer_path(store, sid)
-  if File.exist?(pointer)
-    current = File.read(pointer).strip
-    skip_day_ledger = !current.empty? && current != today
-  end
+  full_session = session_id.empty? ? ENV["CLAUDE_CODE_SESSION_ID"].to_s : session_id
+  skip_day_ledger = !ActiveDelivery.resolve(
+    global_store: store,
+    project_roots: ActiveDelivery.project_roots(plastic_home),
+    session: full_session
+  ).nil?
 rescue StandardError
   nil
 end

package/scripts/hook-record

@@ -16,6 +16,7 @@ require "fileutils"
 require_relative "lib/savepoint"
 require_relative "lib/lock"
 require_relative "lib/session_ledger"
+require_relative "lib/active_delivery"
 
 raw = begin
   $stdin.read
@@ -80,11 +81,20 @@ unless skip_day_ledger
     sid = SessionLedger.short_session_id(nil, session_id)
     today = SessionLedger.day_id
 
+    # A live delivery lock naming this session's full id skips promotion
+    # (344 n2, D5, D12): the lock, not the retired pointer, decides.
     proceed = true
-    pointer = SessionLedger.pointer_path(store, sid)
-    if File.exist?(pointer)
-      current = File.read(pointer).strip
-      proceed = current.empty? || current == today
+    unless session_id.empty?
+      begin
+        held = ActiveDelivery.resolve(
+          global_store: store,
+          project_roots: ActiveDelivery.project_roots(plastic_home),
+          session: session_id
+        )
+        proceed = held.nil?
+      rescue StandardError
+        proceed = true
+      end
     end
 
     if proceed
@@ -135,19 +145,16 @@ unless skip_day_ledger
   end
 end
 
-# --- (d) heartbeat, guarded on the pointer (spec D9) -----------------------
-# Session start writes the `current` pointer; with no pointer at all, session
-# start never ran for this session (a `-p` print session, a resumed
-# background job, an unregistered SessionStart hook), so neither the
-# per-session dir nor its heartbeat is created here -- guarding only the
-# write would still leave an empty directory that heartbeat_age's mtime
-# fallback reports as an orphan just the same.
+# --- (d) heartbeat, guarded on the session tmp dir (344 n2, D4) ------------
+# Session start creates the per-session tmp directory; with no such
+# directory at all, session start never ran for this session (a `-p` print
+# session, a resumed background job, an unregistered SessionStart hook), so
+# the heartbeat is not written and no directory is created here either --
+# the session tmp directory, created by session start, is the guard.
 begin
   store ||= File.join(plastic_home, "store")
   sid ||= SessionLedger.short_session_id(nil, session_id)
-  if File.exist?(SessionLedger.pointer_path(store, sid))
-    SessionLedger.ensure_tmp_root(store)
-    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+  if Dir.exist?(SessionLedger.session_tmp_dir(store, sid))
     File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
   end
 rescue StandardError

package/scripts/hook-savepoint

@@ -4,7 +4,8 @@
 
 # hook-savepoint (intent 311): the PreCompact hook body. Reads the harness
 # payload from stdin (session_id, cwd), takes the Plastic home from argv,
-# writes this session's hand-off for the pointer's day, and prints one
+# writes this session's hand-off for the session's day from the day ledger,
+# and prints one
 # message: the fixed text, plus the written file's path when a session
 # resolved (both harnesses relay the same launcher and the Codex pin feeds
 # both sides the same payload, so the two stay equal). Always exits 0,

package/scripts/hook-session-start

@@ -7,13 +7,12 @@ require "json"
 require "date"
 require "yaml"
 require "fileutils"
-require_relative "lib/bridge"
 require_relative "lib/boot_banner"
 require_relative "lib/qmd_sync"
 require_relative "lib/doctor_core"
 require_relative "lib/session_ledger"
 require_relative "lib/day_summary"
-require_relative "lib/packet_wrapper"
+require_relative "lib/data_boundary"
 require_relative "lib/active_delivery"
 require_relative "lib/runner_core"
 require_relative "lib/runner_watch"
@@ -236,14 +235,14 @@ begin
     if qmd_status[:present]
       # C23 (intent 341, G8): a QMD hit is untrusted text, so it never sits
       # loose in additionalContext alongside the owner's own banners; it
-      # rides inside PacketWrapper's data boundary.
+      # rides inside DataBoundary's data boundary.
       qmd_line = if qmd_status[:all_registered]
         "QMD: #{qmd_status[:registered].size} Plastic collections indexed (search with the qmd skill)."
       else
         "QMD detected — run `qmd-sync register --all` to index your Plastic stores for search."
       end
-      token = PacketWrapper.boundary_token([qmd_line])
-      parts << PacketWrapper.wrap(qmd_line, label: "qmd-hit", source: "qmd-sync", token: token).rstrip
+      token = DataBoundary.boundary_token([qmd_line])
+      parts << DataBoundary.wrap(qmd_line, label: "qmd-hit", source: "qmd-sync", token: token).rstrip
     end
   rescue Exception
     # Any failure (timeout, missing binary, parse error) — stay silent, never crash.
@@ -389,9 +388,11 @@ begin
     end
   end
 
-  # --- Session day ledger: open or join today, write the per-session pointer
-  # and heartbeat (intent 298, spec D4). Best-effort: any failure here degrades
-  # to no ledger context line, never blocks the session.
+  # --- Session day ledger: open or join today, create the tmp dir and write
+  # the heartbeat (344 n2, spec D4). The per-session state retired: hooks
+  # now ask ActiveDelivery.resolve for a live delivery lock instead.
+  # Best-effort: any failure here degrades to no ledger context line, never
+  # blocks the session.
   unless subagent_session
     begin
       templates = File.expand_path("../templates", __dir__)
@@ -409,8 +410,6 @@ begin
       SessionLedger.ensure_tmp_root(store_dir)
       FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store_dir, sid))
       File.write(SessionLedger.heartbeat_path(store_dir, sid), "#{Time.now.utc.iso8601}\n")
-      pointer = SessionLedger.pointer_path(store_dir, sid)
-      File.write(pointer, "#{day}\n") unless File.exist?(pointer)
 
       checklist = SessionLedger.checklist_path(store_dir, day)
       open_count = 0

package/scripts/lib/active_delivery.rb

@@ -1,6 +1,7 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require "yaml"
 require_relative "lock"
 
 # ActiveDelivery (intent 340b, G7c, n4, D10): which intent a session is
@@ -58,4 +59,47 @@ module ActiveDelivery
   def blank?(value)
     value.nil? || value.to_s.strip.empty?
   end
+
+  DEFAULT_PROJECT_ROOTS = ["~/.plastic/projects"].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