@zalom/plastic 1.0.0-beta.3 → 1.0.0-beta.30

package/scripts/lib/bridge.rb

@@ -6,6 +6,9 @@ require "yaml"
 require "fileutils"
 require "tempfile"
 require "digest"
+require "socket"
+require_relative "worktree"
+require_relative "lock"
 
 module Bridge
   STAGES = %w[what why how exec done].freeze
@@ -18,13 +21,15 @@ module Bridge
   # (<id>--<slug>.md) is never sentineled; it is born complete.
   PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
 
-  # Stale-bridge purge window (intent 67). The bridge file is ephemeral
-  # live-session gate state, NOT a continuation source: an intent is resumed from
-  # its savepoint.md ledger, never from a /tmp bridge. So any bridge older than
-  # this window is dead weight and safe to purge, regardless of arm state. No
-  # real session stays live for two days, so a 48h cutoff never removes a bridge
-  # an active run depends on.
-  PURGE_AGE_SECONDS = 48 * 3600   # 48 hours
+  # Bridge cleanup is terminal-state, not age-based (intent 80). A bridge is dead
+  # weight ONLY once its intent is terminal (no longer in its store's INDEX.md
+  # `## Active` block); such bridges are purged. An Active intent's bridge is kept
+  # unconditionally, because while the intent is live the bridge is still load-
+  # bearing: it is the continuation signal (a parked or interrupted run resumes
+  # from it) and the anti-collision lock (it keys the per-session statusline so
+  # parallel sessions do not overwrite each other). An age window was the wrong
+  # axis: it left dead bridges resident for ~2 days AND could reap bridges of
+  # interrupted-but-still-active intents, which are exactly the ones to preserve.
 
   def self.intent_file(intent_dir)
     dir_name = File.basename(intent_dir)
@@ -50,6 +55,31 @@ module Bridge
     value.nil? || value.to_s.strip.empty?
   end
 
+  # Raised by arm when the delivery lock cannot be acquired (held elsewhere,
+  # stale, excluded, or corrupt). The message names the resolving command.
+  class LockHeldError < StandardError; end
+
+  # The absolute intent dir a bridge points at, or nil.
+  def self.bridge_intent_dir(bridge_data)
+    return nil unless bridge_data.is_a?(Hash)
+    info = bridge_data["intent"] || {}
+    store = info["store"]
+    dir = info["dir"]
+    (store && dir) ? File.expand_path("#{store}/#{dir}") : nil
+  end
+
+  # Bridge-cache copy of the durable lock file's fields (D2: the bridge is a
+  # CACHE; the file is the truth). Never carries a pid.
+  def self.lock_cache(lock_data)
+    {
+      "owner_session" => lock_data["owner_session"],
+      "acquired_at" => lock_data["acquired_at"],
+      "host" => lock_data["host"],
+      "type" => lock_data["type"],
+      "delegates" => Array(lock_data["delegates"]),
+    }
+  end
+
   # Deterministic, session-id-less bridge key derived from store + intent id.
   # Stable across processes so a session-less arm and a later session-less
   # gate-check resolve to the same bridge file.
@@ -57,12 +87,19 @@ module Bridge
     "auto-" + Digest::SHA256.hexdigest("#{store}/#{intent_id}")[0, 10]
   end
 
-  # Resolve a bridge session: first non-empty of explicit, CLAUDE_SESSION_ID,
-  # then a derived key. Never returns nil/empty. Whitespace-only counts as empty.
+  # Resolve a bridge session: first non-empty of explicit (the stdin session_id),
+  # CLAUDE_CODE_SESSION_ID, then a derived key. Never returns nil/empty.
+  # Whitespace-only counts as empty.
+  #
+  # The CLAUDE_CODE_SESSION_ID fallback (intent 79) carries the bg/headless real
+  # session id (Claude Code passes session_id on stdin, not via an env var; the
+  # headless id lives in CLAUDE_CODE_SESSION_ID). Keying by the real id (instead of
+  # a derived hash) lets the statusline, which receives that same id on stdin, find
+  # the bridge by direct filename lookup.
   def self.resolve_session(explicit, intent_id:, store:)
     return explicit.to_s.strip unless blank?(explicit)
-    env = ENV["CLAUDE_SESSION_ID"]
-    return env.to_s.strip unless blank?(env)
+    code_env = ENV["CLAUDE_CODE_SESSION_ID"]
+    return code_env.to_s.strip unless blank?(code_env)
     derive_key(store, intent_id)
   end
 
@@ -103,6 +140,22 @@ module Bridge
     end
     return nil if parsed.empty?
 
+    has_session = !blank?(session)
+
+    # Strict per-session ownership (intent 90): when the caller HAS a session, a foreign
+    # session's bridge is NEVER a valid resolution. Own-session and the derived-key case both
+    # reduce to candidate["session"] == session (the derived key IS the session that armed the
+    # bridge). A caller that owns no bridge resolves to nil, so its gates fail open instead of
+    # inheriting another session's armed intent.
+    #
+    # When the caller has NO session (truly headless, intent 52), keep the legacy degraded
+    # selection below so a single armed derived-key bridge is still discoverable - the hook
+    # cannot know the session there, and a lone armed intent must still gate.
+    if has_session
+      parsed = parsed.select { |c| c[:data]["session"].to_s == session.to_s }
+      return nil if parsed.empty?
+    end
+
     auto = parsed.select { |c| c[:data].dig("build", "auto") == true }
     pool = auto.empty? ? parsed : auto
 
@@ -116,31 +169,78 @@ module Bridge
           cwd_abs.start_with?("#{store_abs}/") ||
           store_abs.start_with?("#{cwd_abs}/")
       end
-      pool = matching unless matching.empty?
+      # Hard cwd filter when the caller has a session (intent 90): a non-matching store
+      # excludes the candidate outright. Without a session, keep the best-effort revert
+      # (intent 52) so a lone armed bridge is still found when cwd does not overlap its store.
+      pool = has_session ? matching : (matching.empty? ? pool : matching)
     end
 
     pool.max_by { |c| c[:mtime] }&.fetch(:data)
   end
 
-  # --- Stale-bridge purge (intent 67) ---------------------------------------
-  #
-  # Remove stale tmp/plastic-*.json bridge files so discover_bridge's per-fire
-  # scan stays bounded. Best-effort and non-raising: returns the array of removed
-  # paths. Continuation does not depend on these files (an intent resumes from its
-  # savepoint.md ledger), so the only safety rule is age: a bridge older than
-  # max_age_seconds is purged regardless of arm state, while anything newer is kept
-  # (it may be a live run). The current session's own bridge is never purged
+  # --- Terminal-state bridge purge (intent 80) -------------------------------
+
+  # True iff the intent is Active in its store's INDEX.md. An INDEX.md lives at
+  # the PARENT of the store/ dir the bridge records, so we resolve it from the
+  # bridge's intent.store. Non-raising: any failure (missing/unreadable INDEX,
+  # bad arg) returns false, which means "not active" so the caller treats the
+  # bridge as purgeable. `index_active_ids` is a pure-data test seam: when an
+  # Array of id strings is supplied, membership is checked against it directly
+  # with no file read.
+  def self.intent_active?(intent_id, store:, index_active_ids: nil)
+    target = intent_id.to_s
+    return index_active_ids.include?(target) if index_active_ids.is_a?(Array)
+
+    index = File.join(File.dirname(store.to_s), "INDEX.md")
+    return false unless File.exist?(index)
+
+    in_active = false
+    File.foreach(index) do |line|
+      stripped = line.chomp
+      if stripped == "## Active"
+        in_active = true
+        next
+      end
+      next unless in_active
+      break if stripped.start_with?("## ") # next section ends the Active block
+      m = stripped.match(/^- \[(\S+) +—/)
+      return true if m && m[1] == target
+    end
+    false
+  rescue StandardError
+    false
+  end
+
+  # Remove tmp/plastic-*.json bridge files whose intent is terminal, so
+  # discover_bridge's per-fire scan stays bounded. Best-effort and non-raising:
+  # returns the array of removed paths. A bridge is purged when it cannot be
+  # parsed, has no intent.id, has no intent.store, or its intent is not Active in
+  # its store's INDEX.md. An Active intent's bridge is kept (continuation signal +
+  # anti-collision lock), and the current session's own bridge is never purged
   # (preserves the disarm_auto contract that it stays readable). Wired into
   # arm_auto and disarm_auto so both manual and auto delivery keep the temp dir
-  # clean.
-  def self.purge_stale_bridges(session:, now: Time.now, max_age_seconds: PURGE_AGE_SECONDS,
-                               tmp: tmp_dir)
+  # clean at deterministic work boundaries.
+  def self.purge_done_bridges(session:, tmp: tmp_dir)
     current = path(session, tmp: tmp)
     removed = []
     Dir.glob(File.join(tmp, "plastic-*.json")).each do |f|
       next if f == current
       begin
-        next if (now - File.mtime(f)) < max_age_seconds
+        data = JSON.parse(File.read(f)) rescue nil
+        keep = false
+        if data
+          id = data.dig("intent", "id")
+          store = data.dig("intent", "store")
+          keep = !blank?(id) && !blank?(store) && intent_active?(id, store: store)
+          # Never purge a bridge whose intent still holds a delivery lock
+          # (intent 108, D6): the End tail clears the lock BEFORE the bridge
+          # becomes purge-eligible, so a held lock means the tail is not done.
+          unless keep
+            dir = bridge_intent_dir(data)
+            keep = !dir.nil? && File.exist?(Lock.path(dir))
+          end
+        end
+        next if keep
         File.delete(f)
         removed << f
       rescue Errno::ENOENT
@@ -152,7 +252,7 @@ module Bridge
     end
     removed
   rescue => e
-    $stderr.puts "plastic: purge_stale_bridges failed: #{e.message}"
+    $stderr.puts "plastic: purge_done_bridges failed: #{e.message}"
     removed || []
   end
 
@@ -224,6 +324,51 @@ module Bridge
     end
   end
 
+  # --- Gate-boundary narration (intent 84, Lever 1) -------------------------
+  #
+  # ONE concise sentence that states what happened AND what's next, preserving
+  # the `Next: ...` hint the agent consumes. Pure and side-effect-free so the
+  # hook stays a thin caller and the formatter is unit-testable in isolation.
+  # No "Stage transition: X -> Y" prose, no arrow; a colon/parentheses carry the
+  # stage word. Returns a single line (no embedded newlines).
+  STAGE_LABELS = {
+    "what" => "What", "why" => "Why", "how" => "How",
+    "exec" => "Exec", "done" => "Done"
+  }.freeze
+
+  NEXT_HINTS = {
+    "why" => "write spec.md",
+    "how" => "Why complete. Invoke plastic-auto to deliver autonomously, or write plan.md manually.",
+    "exec" => "How complete. Invoke plastic-auto or plastic-executing-plan to execute, or work through the checklist manually.",
+    "done" => "Exec complete. Intent must be completed now — write outcome.md, update INDEX.md, auto-commit. Use plastic-auto or do it manually."
+  }.freeze
+
+  def self.stage_label(stage)
+    STAGE_LABELS[stage] || stage.to_s
+  end
+
+  # Build the gate-hook `additionalContext` sentence.
+  #   transition:      "PLASTIC: How reached (plan.md written). Next: <hint>"
+  #   same-stage write: "PLASTIC: plan.md written (How). Next: <hint>"
+  # `new_missing` (missing files for the new stage) takes precedence over the
+  # stage hint, exactly as before, so the `Next:` content is unchanged.
+  def self.gate_narration(old_stage:, new_stage:, basename:, new_missing:, next_hints: NEXT_HINTS)
+    head = if old_stage != new_stage
+             "PLASTIC: #{stage_label(new_stage)} reached (#{basename} written)."
+           else
+             "PLASTIC: #{basename} written (#{stage_label(new_stage)})."
+           end
+
+    nxt =
+      if Array(new_missing).any?
+        "Next: #{Array(new_missing).join(", ")}"
+      elsif next_hints[new_stage]
+        "Next: #{next_hints[new_stage]}"
+      end
+
+    nxt ? "#{head} #{nxt}" : head
+  end
+
   # --- Cycle-step savepoint ledger (intent 34) ------------------------------
   #
   # savepoint.md is a deterministic, append-only, one-line-per-milestone ledger
@@ -256,8 +401,31 @@ module Bridge
     end.compact
   end
 
-  # Append a milestone line for file_path if (and only if) it is a milestone
-  # not already recorded. Returns true when a line was written, false otherwise.
+  # (stage, milestone) pairs already recorded in the ledger. The pair (not the
+  # milestone text alone) is the dedup key, because state-from-ledger lines like
+  # `Why  started` and `How  started` share the milestone text "started" while
+  # being distinct events (intent 81).
+  def self.savepoint_recorded_pairs(intent_dir)
+    f = File.join(intent_dir, SAVEPOINT_FILE)
+    return [] unless File.exist?(f)
+    File.read(f).each_line.filter_map do |line|
+      parts = line.strip.split(/\s{2,}/)
+      parts.length >= 3 ? [parts[1], parts[2]] : nil
+    end
+  end
+
+  # Append one ledger line for (stage, milestone) unless that pair is already
+  # recorded. The single append primitive shared by every line class. Returns
+  # true when a line was written, false when it was a no-op.
+  def self.append_savepoint_line(intent_dir, stage, milestone, now)
+    return false if savepoint_recorded_pairs(intent_dir).include?([stage, milestone])
+    line = "#{now.utc.iso8601}  #{stage}  #{milestone}\n"
+    File.open(File.join(intent_dir, SAVEPOINT_FILE), "a") { |io| io.write(line) }
+    true
+  end
+
+  # Append the artifact-landing milestone for file_path if (and only if) it is a
+  # milestone not already recorded. Returns true when a line was written.
   def self.append_savepoint(intent_dir, file_path, now: Time.now)
     basename = File.basename(file_path)
     stage, milestone = savepoint_milestone(intent_dir, basename)
@@ -265,11 +433,62 @@ module Bridge
     # A sentinel-marked lifecycle file logs NO milestone (the stage is not real
     # yet). The intent file is never sentineled, so it still logs its What line.
     return false unless stage_file_present?(File.join(intent_dir, basename))
-    return false if savepoint_recorded_milestones(intent_dir).include?(milestone)
 
-    line = "#{now.utc.iso8601}  #{stage}  #{milestone}\n"
-    File.open(File.join(intent_dir, SAVEPOINT_FILE), "a") { |io| io.write(line) }
-    true
+    append_savepoint_line(intent_dir, stage, milestone, now)
+  end
+
+  # --- State-from-ledger: pre-stage, exec-start, and terminal lines (81) ------
+  #
+  # On top of intent 34's artifact-landing milestones, the ledger gains:
+  #   - `started` lines, one per cycle stage entry (pre-stage, written by the
+  #     PreToolUse savepoint hook the moment a stage's artifact is first written);
+  #   - an `Exec  started` companion emitted when checklist.md lands;
+  #   - a terminal `Done  delivered|abandoned` line written by the completion path.
+  # None of these are derivable from files on disk, so they are deliberately NOT
+  # part of savepoint_milestone and are never regenerated by rebuild_savepoint:
+  # a rebuilt ledger is the file-landing skeleton, the live ledger is richer.
+
+  # Map a written filename to the [stage, "started"] pre-stage milestone, or nil.
+  # spec.md => entering Why, plan.md => entering How. checklist.md/outcome.md do
+  # not open a stage (checklist's Exec-start is the append_exec_started companion).
+  def self.savepoint_started_milestone(basename)
+    case basename
+    when "spec.md" then ["Why", "started"]
+    when "plan.md" then ["How", "started"]
+    end
+  end
+
+  # Append the pre-stage `started` line for file_path, iff: the basename opens a
+  # stage, the stage is genuinely starting (its artifact is not yet a REAL file,
+  # so a sentinel placeholder still counts as "starting"), and the pair is not
+  # already recorded. Returns true when a line was written.
+  def self.append_started_savepoint(intent_dir, file_path, now: Time.now)
+    basename = File.basename(file_path)
+    stage, milestone = savepoint_started_milestone(basename)
+    return false unless milestone
+    return false if stage_file_present?(File.join(intent_dir, basename))
+
+    append_savepoint_line(intent_dir, stage, milestone, now)
+  end
+
+  # Append the `Exec  started` companion (emitted when checklist.md lands, in the
+  # same PostToolUse event as the `How  checklist.md created` line). Idempotent.
+  def self.append_exec_started(intent_dir, now: Time.now)
+    append_savepoint_line(intent_dir, "Exec", "started", now)
+  end
+
+  TERMINAL_DISPOSITIONS = %w[delivered abandoned].freeze
+
+  # Append the terminal bookend `Done  delivered|abandoned`, written by the
+  # completion path when an intent transfers to INDEX's Completed/Abandoned
+  # section. Idempotent per disposition. Raises on an unknown disposition.
+  def self.append_terminal_savepoint(intent_dir, disposition, now: Time.now)
+    unless TERMINAL_DISPOSITIONS.include?(disposition)
+      raise ArgumentError,
+            "disposition must be one of #{TERMINAL_DISPOSITIONS.join(', ')}, got #{disposition.inspect}"
+    end
+
+    append_savepoint_line(intent_dir, "Done", disposition, now)
   end
 
   # Reconstruct the ledger from files on disk (timestamps from mtimes), in
@@ -290,7 +509,7 @@ module Bridge
     lines.length
   end
 
-  def self.derive(session, intent_id:, intent_dir:, store:, name:)
+  def self.derive(session, intent_id:, intent_dir:, store:, name:, tmp: tmp_dir)
     stage = derive_stage(intent_dir)
     has = has_files(intent_dir)
     missing = missing_for_stage(stage, intent_dir) - has
@@ -320,10 +539,28 @@ module Bridge
         "context_pct" => 0,
         "warning_at" => 80,
         "critical_at" => 90
+      },
+      # Worktree isolation block (intent 73c). Born unprovisioned; arm_auto calls
+      # Worktree.provision to fill it. code/store are abs paths or null.
+      "worktree" => {
+        "code" => nil,
+        "code_branch" => nil,
+        "store" => nil,
+        "store_branch" => nil,
+        "provisioned" => false
+      },
+      # Delivery-lock CACHE block (intent 108, D2). The durable truth is the
+      # delivery.lock file in the intent dir; arm fills this cache from it.
+      "lock" => {
+        "owner_session" => nil,
+        "acquired_at" => nil,
+        "host" => nil,
+        "type" => nil,
+        "delegates" => []
       }
     }
 
-    write(session, data)
+    write(session, data, tmp: tmp)
     data
   end
 
@@ -382,31 +619,157 @@ module Bridge
 
   # --- Auto mode (intent 27) ---
 
-  # Arm auto mode for a session+intent. Works even when no bridge exists yet
-  # (mid-session intent creation). Re-derives intent state, then sets build.auto.
-  def self.arm_auto(session, intent_id:, intent_dir:, store:, name:)
+  # Shared arming spine (intent 96): resolve the session key, derive intent state,
+  # set the caller-controlled auto flag, acquire the delivery lock, provision the
+  # per-intent worktrees, persist, and purge terminal bridges. arm_auto (auto: true)
+  # and arm_guided (auto: false) are thin delegators so the lock-stamp + provision
+  # behaviour stays identical across both modes. Works even when no bridge exists
+  # yet (mid-session intent creation).
+  def self.arm(session, intent_id:, intent_dir:, store:, name:, auto:)
     key = resolve_session(session, intent_id: intent_id, store: store)
-    if blank?(session) && blank?(ENV["CLAUDE_SESSION_ID"])
-      $stderr.puts "plastic: no session id available; arming auto with derived bridge key #{key}"
+    if blank?(session) && blank?(ENV["CLAUDE_CODE_SESSION_ID"])
+      $stderr.puts "plastic: no session id available; arming with derived bridge key #{key}"
     end
     data = derive(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
-    data["build"]["auto"] = true
+    data["build"]["auto"] = auto
+
+    # Acquire the durable delivery lock (D1/D2): session-keyed, O_EXCL, in the
+    # intent dir. The bridge lock block is a cache of the file.
+    intent_dir_abs = File.expand_path(intent_dir)
+    status, lock_data = Lock.acquire(intent_dir_abs, session: key)
+    case status
+    when :acquired, :owned
+      data["lock"] = lock_cache(lock_data)
+    when :held
+      raise LockHeldError, "delivery lock for intent #{intent_id} is held by " \
+        "session #{lock_data && lock_data['owner_session']}; run /plastic-lock status"
+    when :stale
+      raise LockHeldError, "delivery lock for intent #{intent_id} is stale " \
+        "(owner #{lock_data && lock_data['owner_session']}); run /plastic-lock " \
+        "reclaim to take it over with an audit"
+    when :excluded
+      raise LockHeldError, "a #{lock_data && lock_data['type']} lock is active on " \
+        "intent #{intent_id}; run /plastic-lock status"
+    when :corrupt
+      raise LockHeldError, "delivery.lock for intent #{intent_id} is unreadable; " \
+        "run /plastic-lock fix"
+    end
+
+    # Provision the per-intent worktrees (mandatory code worktree for project
+    # intents; fail-open for non-git / global-only). Never let a provision error
+    # break arming: the lock and auto flag still matter.
+    begin
+      Worktree.provision(data)
+    rescue => e
+      $stderr.puts "plastic: worktree provision raised, continuing unprovisioned: #{e.message}"
+    end
+
     write(key, data)
-    purge_stale_bridges(session: key)
+    purge_done_bridges(session: key)
     data
   end
+  private_class_method :arm
 
-  # Disarm auto mode. No-op if no bridge exists for the session.
+  # Arm auto mode for a session+intent. Works even when no bridge exists yet
+  # (mid-session intent creation). Re-derives intent state, then sets build.auto.
+  def self.arm_auto(session, intent_id:, intent_dir:, store:, name:)
+    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name, auto: true)
+  end
+
+  # Acquire the delivery lock WITHOUT auto mode (intent 96 / Start guided branch).
+  # Mirrors arm_auto's lock-stamp + worktree provision but leaves build.auto = false.
+  # Same signature as arm_auto; disarm_auto (mode-agnostic) releases a guided lock.
+  def self.arm_guided(session, intent_id:, intent_dir:, store:, name:)
+    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name, auto: false)
+  end
+
+  # Disarm. No-op if no bridge exists for the session. End-tail order (D6):
+  # worktrees are merged/removed FIRST (the verify step is the caller's,
+  # before disarm), then the delivery lock is cleared, and only then does the
+  # bridge become purge-eligible. purge_done_bridges enforces the same order
+  # defensively by skipping any bridge whose intent still holds a lock.
   def self.disarm_auto(session)
     data = read(session)
     return nil unless data
     data["build"] ||= {}
     data["build"]["auto"] = false
+
+    # Release the worktrees the matching arm provisioned (intent 73c). Non-fatal:
+    # a release error must not block disarming. CLEANUP (73c3) refines the
+    # merge-vs-remove policy on the completion/release path.
+    begin
+      Worktree.release(data)
+    rescue => e
+      $stderr.puts "plastic: worktree release raised, continuing: #{e.message}"
+    end
+
+    dir = bridge_intent_dir(data)
+    if dir
+      owner = data.dig("lock", "owner_session")
+      owner = session if blank?(owner)
+      Lock.release(dir, session: owner)
+    end
+    data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
+                     "host" => nil, "type" => nil, "delegates" => [] }
+
     write(session, data)
-    purge_stale_bridges(session: session)
+    purge_done_bridges(session: session)
     data
   end
 
+  # One deterministic, idempotent repair (intent 108, D5): diagnose, remove
+  # faulty own-side state, rebuild the durable lock AND the bridge cache from
+  # disk truth for the current session. Legacy /tmp-only pid locks are
+  # migrated here: the delivery.lock file is created and the cache rebuilt
+  # without a pid. NEVER touches a fresh foreign lock (reports "held"); a
+  # stale foreign lock reports "stale" and is taken only by the explicit
+  # reclaim verb (Lock.takeover). Two entry points call this: the
+  # plastic-lock CLI and /plastic-intent-starting (self-healing boarding).
+  def self.repair_lock(session, intent_id:, intent_dir:, store:, name:,
+                       now: Time.now, tmp: tmp_dir)
+    key = resolve_session(session, intent_id: intent_id, store: store)
+    dir = File.expand_path(intent_dir)
+    actions = []
+
+    if Lock.corrupt?(dir)
+      File.delete(Lock.path(dir))
+      actions << "removed corrupt delivery.lock"
+    end
+
+    lock = Lock.read(dir)
+    if lock && !Lock.authorized?(lock, key)
+      if Lock.fresh?(dir, now: now)
+        return { "status" => "held", "owner" => lock["owner_session"],
+                 "actions" => actions, "session" => key }
+      end
+      return { "status" => "stale", "owner" => lock["owner_session"],
+               "actions" => actions, "session" => key,
+               "hint" => "run /plastic-lock reclaim to take over with an audit" }
+    end
+
+    if lock
+      Lock.heartbeat(dir, session: key, now: now)
+      lock_data = Lock.read(dir)
+      role = lock_data["owner_session"].to_s == key ? "owner" : "delegate"
+      actions << "lock kept (#{role})"
+    else
+      status, lock_data = Lock.acquire(dir, session: key, now: now)
+      actions << "lock #{status}"
+    end
+
+    previous = read(key, tmp: tmp)
+    auto = !!(previous && previous.dig("build", "auto"))
+    data = derive(key, intent_id: intent_id, intent_dir: dir, store: store,
+                  name: name, tmp: tmp)
+    data["build"]["auto"] = auto
+    data["lock"] = lock_cache(lock_data)
+    write(key, data, tmp: tmp)
+    actions << "bridge rebuilt from disk (stage #{data['build']['stage']})"
+
+    { "status" => "repaired", "actions" => actions,
+      "lock" => lock_data, "session" => key }
+  end
+
   # Decide whether a code edit should be blocked while auto mode is armed.
   # Returns a reason string to BLOCK, or nil to ALLOW.
   #
@@ -441,6 +804,182 @@ module Bridge
       "(blocked edit: #{file_abs})"
   end
 
+  # --- Fail-closed lock gate (intent 96) -------------------------------------
+
+  # Returns a reason String to BLOCK, or nil to ALLOW. Decides from the
+  # durable delivery.lock in the TARGET intent dir (D2): the bridge argument
+  # only supplies a fallback session id, so a missing or disagreeing bridge
+  # never changes the verdict. Every deny names the exact resolving command
+  # (D5). ALLOW: non-intent paths, not-yet-active intents, and any session the
+  # target's lock names as owner or delegate (even when stale: a stale lock is
+  # still its owner's until an explicit takeover).
+  def self.lock_gate_decision(bridge_data, file_path, session: nil,
+                              ttl: Lock::TTL_SECONDS, now: Time.now)
+    return nil if blank?(file_path)
+
+    target_dir = intent_dir_for(file_path)
+    return nil unless target_dir
+    id = intent_id_from_dir(target_dir)
+    store = File.dirname(target_dir)
+    return nil unless id && intent_active?(id, store: store)
+
+    sess = session
+    sess = bridge_data["session"] if blank?(sess) && bridge_data.is_a?(Hash)
+
+    lock = Lock.read(target_dir)
+    if lock
+      return nil if Lock.authorized?(lock, sess)
+      if Lock.fresh?(target_dir, ttl: ttl, now: now)
+        return "intent #{id} delivery lock is held by session " \
+               "#{lock['owner_session']}. Back off; if you are the owner's " \
+               "subagent, the owner must run: plastic-lock delegate " \
+               "--intent-dir #{target_dir} --session <your-session-id>. " \
+               "Inspect with /plastic-lock status"
+      end
+      return "intent #{id} has a stale delivery lock (owner " \
+             "#{lock['owner_session']}); run /plastic-lock reclaim to take " \
+             "it over, or /plastic-lock fix"
+    end
+    if Lock.corrupt?(target_dir)
+      return "delivery.lock for intent #{id} is unreadable; run /plastic-lock fix"
+    end
+    "no delivery lock held for intent #{id}; run /plastic-intent-starting " \
+      "to lock and begin"
+  end
+
+  # A session holds an intent's lock iff the durable delivery.lock in the
+  # intent dir names it as owner or delegate (D1/D4). The bridge is only a
+  # cache: the lock FILE decides, so a wiped /tmp or a clobbered bridge never
+  # strands the owner. No pid is consulted anywhere.
+  def self.holds_live_lock?(bridge_data, session: nil)
+    sess = session
+    sess = bridge_data["session"] if blank?(sess) && bridge_data.is_a?(Hash)
+    return false if blank?(sess)
+    dir = bridge_intent_dir(bridge_data)
+    return false unless dir
+    Lock.holds?(dir, session: sess)
+  end
+
+  # "<id>" from a ".../store/<id>--<slug>" dir, else nil.
+  def self.intent_id_from_dir(dir)
+    base = File.basename(dir.to_s)
+    base.include?("--") ? base.split("--", 2).first : nil
+  end
+
+  # --- Worktree isolation gate (intent 73c2) ---
+
+  # Returns a reason String to BLOCK, or nil to ALLOW. Two independent rules,
+  # both fail-open by construction:
+  #
+  #   1. When the bridge has a provisioned code worktree, a code edit (a target
+  #      outside ~/.plastic and outside this intent's store dir) MUST land inside
+  #      worktree["code"]; otherwise BLOCK and name the expected worktree path.
+  #   2. When the target lives inside ANOTHER intent's store dir whose bridge lock
+  #      is held by a LIVE non-owner session, BLOCK (non-owner edit to an active
+  #      intent).
+  #
+  # Fails open (returns nil) when provisioned is false (non-git / global-only) or
+  # the bridge carries no worktree/lock blocks. Logs nothing on the allow path.
+  def self.worktree_gate_decision(bridge_data, file_path, home: Dir.home, current_session: nil)
+    return nil unless bridge_data.is_a?(Hash)
+    return nil if blank?(file_path)
+
+    file_abs = File.expand_path(file_path.to_s)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+    under_plastic = file_abs == plastic_home || file_abs.start_with?("#{plastic_home}/")
+
+    intent_info = bridge_data["intent"] || {}
+    store = intent_info["store"]
+    dir = intent_info["dir"]
+    intent_dir_abs = (store && dir) ? File.expand_path("#{store}/#{dir}") : nil
+    under_own_intent = intent_dir_abs &&
+                       (file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/"))
+
+    # Rule 1 (fixed in intent 108, D7): confinement applies ONLY to paths
+    # inside the project repo. The repo root is derived from the provisioned
+    # code worktree path, which is <repo>/.claude/worktrees/{id}--{slug} by
+    # construction, so no git call is needed. Paths outside the repo (agent
+    # memory dirs, scratch files, unrelated checkouts) are not this gate's
+    # business; the 2026-07-02 memory-dir denial came from treating everything
+    # outside the worktree as the shared checkout.
+    worktree = bridge_data["worktree"] || {}
+    if worktree["provisioned"] == true
+      code = worktree["code"].to_s
+      if !blank?(code) && !under_plastic && !under_own_intent
+        code_abs = File.expand_path(code)
+        repo_abs = File.expand_path(File.join(code_abs, "..", "..", ".."))
+        inside_repo = file_abs == repo_abs || file_abs.start_with?("#{repo_abs}/")
+        inside_code = file_abs == code_abs || file_abs.start_with?("#{code_abs}/")
+        if inside_repo && !inside_code
+          id = intent_info["id"]
+          return "intent #{id} is isolated to its worktree - edit project code " \
+                 "inside #{code_abs}, not the shared checkout. (blocked edit: #{file_abs})"
+        end
+      end
+    end
+
+    # Rule 2: do not edit another intent's locked, live store dir.
+    if under_plastic
+      reason = non_owner_store_edit_reason(file_abs, plastic_home, intent_dir_abs,
+                                           home: home, current_session: current_session,
+                                           own_session: bridge_data["session"])
+      return reason if reason
+    end
+
+    nil
+  end
+
+  # Helper for rule 2. A store dir is `<plastic_home>/store/{id}--{slug}` (global)
+  # or `<plastic_home>/projects/{slug}/store/{id}--{slug}` (project). When the
+  # edit target sits inside such a dir that is NOT this intent's own dir, and a
+  # live non-owner session holds that intent's bridge lock, BLOCK.
+  def self.non_owner_store_edit_reason(file_abs, plastic_home, own_intent_dir_abs,
+                                       home:, current_session:, own_session:)
+    return nil if own_intent_dir_abs &&
+                  (file_abs == own_intent_dir_abs || file_abs.start_with?("#{own_intent_dir_abs}/"))
+
+    parsed = parse_store_target(file_abs, plastic_home)
+    return nil unless parsed
+
+    session = blank?(current_session) ? own_session : current_session
+    held = Worktree.lock_held_by_other?(
+      intent_id: parsed[:id], store: parsed[:store],
+      current_session: session, home: home,
+    )
+    return nil unless held
+
+    "intent #{parsed[:id]} is owned by another live session — its delivery lock " \
+      "is held elsewhere. Back off; do not edit #{file_abs}."
+  end
+
+  # Resolve an edit target inside a store to {id:, store:} for the intent dir it
+  # belongs to, or nil if the path is not inside an `{id}--{slug}` intent dir.
+  def self.parse_store_target(file_abs, plastic_home)
+    rels = []
+    global_store = File.join(plastic_home, "store")
+    if file_abs.start_with?("#{global_store}/")
+      rels << [file_abs[(global_store.length + 1)..], global_store]
+    end
+    projects = File.join(plastic_home, "projects")
+    if file_abs.start_with?("#{projects}/")
+      tail = file_abs[(projects.length + 1)..].to_s
+      parts = tail.split(File::SEPARATOR)
+      if parts.length >= 2 && parts[1] == "store"
+        pstore = File.join(projects, parts[0], "store")
+        rels << [file_abs[(pstore.length + 1)..], pstore]
+      end
+    end
+
+    rels.each do |rel, store_dir|
+      next if blank?(rel)
+      first = rel.split(File::SEPARATOR).first.to_s
+      idx = first.index("--")
+      next unless idx && idx > 0
+      return { id: first[0...idx], store: store_dir }
+    end
+    nil
+  end
+
   # --- Bash-edit gate (intent 27a) ---
 
   # Extract the set of file paths a Bash command writes to. Conservative by
@@ -457,6 +996,7 @@ module Bridge
     # Split on command separators for per-segment utility parsing.
     command.split(/[;\n]|&&|\|\||\|/).each do |segment|
       targets.concat(bash_utility_targets(segment))
+      targets.concat(interpreter_write_targets(segment))
     end
     targets.uniq
   end
@@ -532,18 +1072,56 @@ module Bridge
     path == "/dev/null" || path.start_with?("/dev/")
   end
 
-  # Decide whether a Bash command should be blocked under the auto-mode code
-  # gate. Resolves each write target against cwd and applies the SAME policy as
-  # code_gate_decision. Returns the first block reason, or nil to allow.
-  def self.bash_gate_decision(bridge_data, command, cwd:, home: Dir.home)
+  # --- Interpreter inline-code writes (intent 108, D7) ---
+
+  INTERPRETER_RE = /\b(ruby|python3?|perl|node)\b(?:\s+\S+)*?\s+(-e|-c)\s+(.+)\z/m.freeze
+
+  # Write verbs that mark inline code as file-mutating. Conservative: reads
+  # (File.read, puts) never match.
+  WRITE_VERB_RE = /File\.(?:write|binwrite|open)|IO\.write|FileUtils\.|
+                   open\s*\([^)]*["'][wa]|writeFileSync|fs\.write/x.freeze
+
+  # Quoted absolute or ~/ paths inside the inline code.
+  INLINE_PATH_RE = %r{["']((?:/|~/)[^"']+)["']}.freeze
+
+  # Paths an interpreter one-liner writes. Flagged only when the inline code
+  # has BOTH a write verb AND a quoted absolute path; everything else (reads,
+  # ARGV-driven paths, the sanctioned arm one-liners) yields no targets.
+  def self.interpreter_write_targets(segment)
+    m = INTERPRETER_RE.match(segment.to_s)
+    return [] unless m
+    util, flag, code = m[1], m[2], m[3]
+    expected = { "ruby" => "-e", "python" => "-c", "python3" => "-c",
+                 "perl" => "-e", "node" => "-e" }[util]
+    return [] unless flag == expected
+    return [] unless WRITE_VERB_RE.match?(code)
+    code.scan(INLINE_PATH_RE).flatten.map { |p| File.expand_path(p) }
+  end
+
+  # Decide whether a Bash command should be blocked. Every write target runs
+  # through the SAME policy stack as a direct tool write: the auto-mode code
+  # gate AND the delivery-lock gate (intent 108, D7), so bash and interpreter
+  # writes cannot bypass the lock. Returns the first block reason, or nil.
+  def self.bash_gate_decision(bridge_data, command, cwd:, home: Dir.home, session: nil)
     bash_write_targets(command).each do |target|
       abs = File.absolute_path?(target) ? target : File.join(cwd, target)
-      reason = code_gate_decision(bridge_data, abs, home: home)
+      abs = File.expand_path(abs)
+      reason = code_gate_decision(bridge_data, abs, home: home) ||
+               lock_gate_decision(bridge_data, abs, session: session)
       return reason if reason
     end
     nil
   end
 
+  # A TRAILING `# plastic-ok` shell comment: the auditable escape for
+  # sanctioned bash/interpreter writes (mirrors the retrieval gate's
+  # `# qmd-ok`). The hook logs every use to ~/.plastic/.cache/gate-escapes.log.
+  PLASTIC_OK_RE = /(?:\A|\s)#\s*plastic-ok\s*\z/.freeze
+
+  def self.bash_escape?(command)
+    PLASTIC_OK_RE.match?(command.to_s.chomp)
+  end
+
   def self.deep_merge(base, overlay)
     result = base.dup
     overlay.each do |key, value|