@zalom/plastic 1.9.0 → 1.10.0

package/scripts/exec-worktree

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# exec-worktree (intent 213, group 2) - finish an intent's code worktree: an order
+# precondition, then Worktree.finish (delivered merges + removes, abandoned removes only).
+#
+# Usage:
+#   exec-worktree --store <path> --id <intent_id> --home <plastic_home> \
+#                 --disposition delivered|abandoned [--session <session_id>]
+#
+# --home accepts either spelling: the OS-home level (the PARENT of .plastic) or the
+# .plastic directory itself. When the given path's basename is literally .plastic, its
+# dirname is used instead. Worktree.finish's home: keyword always wants the OS-home
+# level (Worktree.home_from_store, scripts/lib/worktree.rb:90); this script normalizes
+# both spellings to that so either caller convention works.
+#
+# Steps performed:
+#   0. Resolve inputs: the intent dir, normalize --home, resolve the calling session
+#      (--session, else CLAUDE_CODE_SESSION_ID, else the existing delivery.lock's own
+#      recorded owner_session when non-blank, else nil; unlike start-intent, the
+#      lock-owner fallback IS used here, matching end-intent's teardown resolution order).
+#      Load the bridge (Bridge.read); a nil bridge means there is nothing to finish (exit
+#      0, loud: the worktree this intent provisioned, if any, was NOT removed). No
+#      worktree.code on the bridge means nothing was provisioned (exit 0).
+#   1. The order precondition (delivered only): calls the EXISTING
+#      Bridge.code_gate_decision predicate exactly as it exists. On an auto bridge that
+#      has not reached How, this BLOCKS (exit 2). Bridge.code_gate_decision returns nil
+#      UNCONDITIONALLY on a guided bridge (build.auto != true), so on a guided bridge
+#      this precondition is ADVISORY ONLY: it always passes and the run proceeds. This
+#      script is NOT the enforcement point either way; the hook layer
+#      (scripts/lib/bridge.rb code_gate_decision, wired through scripts/lib/edit_gates.rb)
+#      remains the actual gate. See scripts/lib/exec_worktree.rb's module doc for why the
+#      auto-only condition is never relaxed and never duplicated here.
+#   2. 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.
+#   3. Finish: Worktree.finish(bridge_data, 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).
+#
+# No test suite is run by this script, in any form. verify-intent owns test execution;
+# 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)
+#   1  usage or path-resolution failure
+#   2  the order precondition blocked a delivered disposition (auto bridge, How not
+#      reached)
+#   3  the worktree is not clean, or the merge/removal did not complete (delivered only)
+#   4  lock or session resolution failure
+
+require_relative "lib/exec_worktree"
+
+def parse_args(argv)
+  opts = { store: nil, id: nil, home: nil, disposition: nil, session: nil }
+  i = 0
+  while i < argv.length
+    arg = argv[i]
+    case arg
+    when "--store"       then opts[:store] = argv[i += 1]
+    when "--id"          then opts[:id] = argv[i += 1]
+    when "--home"        then opts[:home] = argv[i += 1]
+    when "--disposition" then opts[:disposition] = argv[i += 1]
+    when "--session"     then opts[:session] = argv[i += 1]
+    else
+      usage_abort("unknown argument #{arg.inspect}")
+    end
+    i += 1
+  end
+  opts
+end
+
+def usage
+  "usage: exec-worktree --store <store_path> --id <intent_id> --home <plastic_home> " \
+    "--disposition delivered|abandoned [--session <session_id>]"
+end
+
+def usage_abort(message)
+  warn "exec-worktree: #{message}"
+  warn usage
+  exit 1
+end
+
+def main(argv)
+  opts = parse_args(argv)
+
+  result = ExecWorktree.run(
+    store: opts[:store], id: opts[:id], home: opts[:home], disposition: opts[:disposition],
+    session: opts[:session], env_session: ENV["CLAUDE_CODE_SESSION_ID"]
+  )
+
+  Array(result[:stderr]).each { |line| warn line }
+  warn usage if result[:exit_code] == ExecWorktree::EXIT_USAGE
+  Array(result[:stdout]).each { |line| puts line }
+  exit result[:exit_code]
+end
+
+main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/hash-intent

@@ -13,7 +13,7 @@ fi
 
 # Try Ruby first (macOS/Linux default)
 if command -v ruby &>/dev/null; then
-  ruby -r digest -e 'puts Digest::SHA256.hexdigest(ARGV[0]).to_i(16).to_s(36)[0,6]' "$INTENT_NAME"
+  env -u RUBYOPT ruby -r digest -e 'puts Digest::SHA256.hexdigest(ARGV[0]).to_i(16).to_s(36)[0,6]' "$INTENT_NAME"
   exit 0
 fi
 

package/scripts/hook-bash-gate

@@ -55,5 +55,24 @@ bridge_data = Bridge.discover_bridge(session: session, cwd: cwd)
 reason = Bridge.bash_gate_decision(bridge_data, command, cwd: cwd, session: session)
 exit 0 unless reason
 
+# Block log (intent 229): one six-field TSV line, hand-rolled here exactly as
+# the escape write above is, so this script keeps requiring only lib/bridge and
+# pays no extra load on every Bash tool call. Best-effort: the block applies
+# regardless.
+begin
+  require "fileutils"
+  require "time"
+  blocklog = File.join(Dir.home, ".plastic", ".cache", "gate-blocks.log")
+  FileUtils.mkdir_p(File.dirname(blocklog))
+  intent_id = bridge_data.is_a?(Hash) ? bridge_data.dig("intent", "id").to_s : ""
+  File.open(blocklog, "a") do |io|
+    io.puts([Time.now.utc.iso8601, "bash-gate", session.to_s, intent_id,
+             command.to_s.gsub(/\s+/, " ").strip,
+             reason.to_s.gsub(/\s+/, " ").strip].join("\t"))
+  end
+rescue StandardError
+  # the block still applies; logging is best-effort
+end
+
 $stderr.puts "PLASTIC GATE — #{reason}"
 exit 2

package/scripts/hook-code-gate

@@ -15,7 +15,10 @@
 #
 # Thin CLI wrapper (intent 244): the gate logic itself lives in
 # scripts/lib/edit_gates.rb, shared with the merged Claude dispatcher
-# (scripts/hook-edit-gates) so the two harnesses cannot drift.
+# (scripts/hook-edit-gates) and, since intent 251, the merged Codex dispatcher
+# (scripts/lib/codex_edit_gates.rb). This wrapper has no production caller on
+# either harness anymore; it remains as the per-gate isolation surface for the
+# hook test suite.
 
 require_relative "lib/edit_gates"
 

package/scripts/hook-continue

@@ -15,7 +15,7 @@ exit 0 unless index_path && File.exist?(index_path)
 dashboard = File.expand_path("dashboard.rb", __dir__)
 exit 0 unless File.exist?(dashboard)
 
-cockpit, _err, status = Open3.capture3("ruby", dashboard, "continue")
+cockpit, _err, status = Open3.capture3({"RUBYOPT" => nil}, "ruby", dashboard, "continue")
 exit 0 unless status.success? && !cockpit.strip.empty?
 
 context = cockpit.rstrip +
@@ -36,7 +36,7 @@ payload = {
 # degrades silently, omitting systemMessage; this hook must never crash
 # UserPromptSubmit over a summary line.
 begin
-  data_json, _data_err, data_status = Open3.capture3("ruby", dashboard, "continue", "--data")
+  data_json, _data_err, data_status = Open3.capture3({"RUBYOPT" => nil}, "ruby", dashboard, "continue", "--data")
   if data_status.success?
     banner = DashboardBanner.render(JSON.parse(data_json))
     payload["systemMessage"] = banner if banner

package/scripts/hook-create-gate

@@ -29,9 +29,12 @@
 #
 # Thin CLI wrapper (intent 244): the gate logic itself lives in
 # scripts/lib/edit_gates.rb, shared with the merged Claude dispatcher
-# (scripts/hook-edit-gates) so the two harnesses cannot drift. Deliberately
-# WITHOUT a top-level rescue, matching this script's behavior before the
-# extraction: an internal exception here has never been caught.
+# (scripts/hook-edit-gates) and, since intent 251, the merged Codex dispatcher
+# (scripts/lib/codex_edit_gates.rb). This wrapper has no production caller on
+# either harness anymore; it remains as the per-gate isolation surface for the
+# hook test suite. Deliberately WITHOUT a top-level rescue, matching this
+# script's behavior before the extraction: an internal exception here has
+# never been caught.
 
 require "json"
 require_relative "lib/edit_gates"

package/scripts/hook-gate-check

@@ -99,6 +99,23 @@ if is_stage_file || is_action_file
   error = Bridge.check_gate(bridge_intent_dir_abs, file_path_abs)
 
   if error
+    # Block log (intent 229): same hand-rolled best-effort write as
+    # hook-bash-gate's; this script keeps its current requires.
+    begin
+      require "fileutils"
+      require "time"
+      blocklog = File.join(Dir.home, ".plastic", ".cache", "gate-blocks.log")
+      FileUtils.mkdir_p(File.dirname(blocklog))
+      File.open(blocklog, "a") do |io|
+        io.puts([Time.now.utc.iso8601, "gate-check", session.to_s,
+                 Bridge.intent_id_from_dir(bridge_intent_dir_abs).to_s,
+                 file_path_abs.to_s.gsub(/\s+/, " ").strip,
+                 error.to_s.gsub(/\s+/, " ").strip].join("\t"))
+      end
+    rescue StandardError
+      # the block still applies; logging is best-effort
+    end
+
     # Gate violation — block the write
     bridge_data["build"]["gate_failures"] = (bridge_data["build"]["gate_failures"] || 0) + 1
     Bridge.write(session, bridge_data)

package/scripts/hook-links-gate

@@ -16,7 +16,10 @@
 #
 # Thin CLI wrapper (intent 244): the gate logic itself lives in
 # scripts/lib/edit_gates.rb, shared with the merged Claude dispatcher
-# (scripts/hook-edit-gates) so the two harnesses cannot drift.
+# (scripts/hook-edit-gates) and, since intent 251, the merged Codex dispatcher
+# (scripts/lib/codex_edit_gates.rb). This wrapper has no production caller on
+# either harness anymore; it remains as the per-gate isolation surface for the
+# hook test suite.
 
 require "json"
 require_relative "lib/edit_gates"

package/scripts/hook-lock-gate

@@ -11,7 +11,10 @@
 #
 # Thin CLI wrapper (intent 244): the gate logic itself lives in
 # scripts/lib/edit_gates.rb, shared with the merged Claude dispatcher
-# (scripts/hook-edit-gates) so the two harnesses cannot drift.
+# (scripts/hook-edit-gates) and, since intent 251, the merged Codex dispatcher
+# (scripts/lib/codex_edit_gates.rb). This wrapper has no production caller on
+# either harness anymore; it remains as the per-gate isolation surface for the
+# hook test suite.
 
 require_relative "lib/edit_gates"
 
@@ -21,8 +24,9 @@ begin
   session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_CODE_SESSION_ID"]
   # Usage: hook-lock-gate <file_path> [session_id] [harness]. Claude's own bash
   # shim never passes a third arg, so harness falls through to Lock's default
-  # (claude, slash form); scripts/codex-hook is the only caller that passes
-  # "codex" here (intent 201 D2).
+  # (claude, slash form). Since intent 251 the merged Codex library
+  # (scripts/lib/codex_edit_gates.rb) sets harness: "codex" directly on the
+  # Context it builds; no caller of this wrapper passes "codex" anymore.
   harness = (ARGV[2] unless ARGV[2].to_s.empty?) || "claude"
 
   ctx = EditGates::Context.new(

package/scripts/hook-savepoint-pre

@@ -16,7 +16,10 @@
 #
 # Thin CLI wrapper (intent 244): the gate logic itself lives in
 # scripts/lib/edit_gates.rb, shared with the merged Claude dispatcher
-# (scripts/hook-edit-gates) so the two harnesses cannot drift.
+# (scripts/hook-edit-gates) and, since intent 251, the merged Codex dispatcher
+# (scripts/lib/codex_edit_gates.rb). This wrapper has no production caller on
+# either harness anymore; it remains as the per-gate isolation surface for the
+# hook test suite.
 
 require_relative "lib/edit_gates"
 

package/scripts/hook-session-start

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # encoding: UTF-8
-# Usage: hook-session-start <index_path> <store_root> <mode> [plugin_root]
+# Usage: hook-session-start <index_path> <plastic_home> <mode> [plugin_root]
 # Outputs hook JSON for the session-start hook. Exits silently if nothing to show.
 
 require "json"
@@ -9,10 +9,16 @@ require "yaml"
 require_relative "lib/bridge"
 require_relative "lib/boot_banner"
 require_relative "lib/qmd_sync"
-require_relative "doctor"
+require_relative "lib/doctor_core"
 
-index_path, store_root, mode, plugin_root = ARGV
-exit 0 unless index_path && store_root && mode
+index_path, plastic_home, mode, plugin_root = ARGV
+exit 0 unless index_path && plastic_home && mode
+
+# Plastic home and the store are two different paths (intent 231). The shim passes
+# home (~/.plastic) as argument 2; the store lives one level below it. Compose the
+# store exactly once here, so no later line re-derives it and no path can gain a
+# doubled store/ segment.
+store_dir = File.join(plastic_home, "store")
 
 # --- Parse INDEX.md ---
 
@@ -47,11 +53,11 @@ end
 bridge_data = nil
 if active.length == 1 && active.first =~ /store\/([\w-]+)\//
   dir_name = $1
-  intent_dir = "#{store_root}/store/#{dir_name}"
+  intent_dir = "#{store_dir}/#{dir_name}"
   session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
   intent_id = dir_name.split("--").first
   intent_name = active.first[/\[([^\]]+)\]/, 1] || "unknown"
-  bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_root, name: intent_name)
+  bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_dir, name: intent_name)
 end
 
 # --- Detect stale future intents ---
@@ -68,7 +74,7 @@ stale_days = 3 if stale_days == 0
 future.each do |f|
   if f =~ /store\/([\w-]+)\//
     dir_name = $1
-    intent_file = "#{store_root}/store/#{dir_name}/#{dir_name}.md"
+    intent_file = "#{store_dir}/#{dir_name}/#{dir_name}.md"
     next unless File.exist?(intent_file)
 
     content = File.read(intent_file)
@@ -88,7 +94,7 @@ current_project = nil
 project_active = []
 project_future = []
 
-projects_path = "#{store_root}/projects.yml"
+projects_path = "#{plastic_home}/projects.yml"
 if File.exist?(projects_path)
   projects = YAML.safe_load(File.read(projects_path)) rescue {}
   cwd = Dir.pwd
@@ -96,7 +102,7 @@ if File.exist?(projects_path)
     project_path = File.expand_path(info["path"])
     if cwd.start_with?(project_path)
       current_project = { "slug" => slug, "parent" => info["parent"], "path" => project_path }
-      project_index = "#{store_root}/projects/#{slug}/INDEX.md"
+      project_index = "#{plastic_home}/projects/#{slug}/INDEX.md"
       if File.exist?(project_index)
         p_section = nil
         File.readlines(project_index).each do |pline|
@@ -122,7 +128,7 @@ end
 
 # --- Load PLASTIC.md conventions ---
 
-plastic_md_path = "#{store_root}/PLASTIC.md"
+plastic_md_path = "#{plastic_home}/PLASTIC.md"
 plastic_md = File.exist?(plastic_md_path) ? File.read(plastic_md_path).strip : nil
 
 # --- Load deprecations ---
@@ -130,7 +136,7 @@ plastic_md = File.exist?(plastic_md_path) ? File.read(plastic_md_path).strip : n
 dep_file = if plugin_root && !plugin_root.empty?
   "#{plugin_root}/deprecations.yml"
 else
-  "#{store_root}/deprecations.yml"
+  "#{plastic_home}/deprecations.yml"
 end
 
 deprecations = []
@@ -147,7 +153,7 @@ rescue
 end
 
 current_version = nil
-version_file = "#{store_root}/VERSION"
+version_file = "#{plastic_home}/VERSION"
 if File.exist?(version_file)
   current_version = File.read(version_file).strip
 elsif plugin_root && !plugin_root.empty?
@@ -167,7 +173,7 @@ end
 # --- Check for available updates (from previous session's check) ---
 
 update_notice = nil
-cache_file = "#{store_root}/.cache/update-check.json"
+cache_file = "#{plastic_home}/.cache/update-check.json"
 if File.exist?(cache_file)
   cache = JSON.parse(File.read(cache_file)) rescue {}
   if cache["updateAvailable"]
@@ -181,7 +187,7 @@ end
 # session: any failure or exception degrades to a banner and we continue.
 
 core_health = begin
-  Doctor.new(plastic_home: store_root).run_core_checks("claude")
+  Doctor.new(plastic_home: plastic_home).run_core_checks("claude")
 rescue
   nil
 end
@@ -212,7 +218,7 @@ parts << ""
 # slow/broken/missing qmd appends nothing and the hook continues cleanly.
 begin
   require "timeout"
-  qmd_status = Timeout.timeout(2) { QmdSync.status(plastic_home: store_root) }
+  qmd_status = Timeout.timeout(2) { QmdSync.status(plastic_home: plastic_home) }
   if qmd_status[:present]
     if qmd_status[:all_registered]
       parts << "QMD: #{qmd_status[:registered].size} Plastic collections indexed (search with the qmd skill)."

package/scripts/lib/apply_patch_envelope.rb

@@ -13,16 +13,27 @@
 # Part 4] the hook stdin schema, including `tool_input.command` as the carrier of
 # the apply_patch envelope text (consumed by scripts/codex-hook).
 #
-# Residual gap (in neither the guide nor 181, per Decision 14): the apply_patch
-# V4A envelope INNER grammar parsed below (`*** Begin/End Patch`, `*** Add/Update/
-# Delete File:`, `*** Move to:`, `+`/`-`/context lines) is not primary-sourced.
-# There is no live Codex to verify it against (the owner has none installed), so
-# this parser is built to the best-known public V4A shape and FAILS OPEN on
-# anything else. Returns [] and warns on any missing or unparseable envelope:
-# gates fail OPEN (orchestrator-locks fail-open rule). The PostToolUse gate-check
-# artifact backstop re-validates the intent file after the write, so a fail-open
-# create-gate is still netted. A real Codex run after delivery is the only future
-# check on this residual.
+# Grammar provenance (intent 239, 2026-08-12). The V4A envelope grammar parsed below
+# is primary-sourced: it is embedded verbatim in the native codex binary and was
+# extracted from codex-cli 0.146.0 into test/fixtures/codex-v4a-grammar.txt, which
+# carries the binary's path, size and SHA256 in its header.
+# test/codex_v4a_grammar_test.rb checks this parser's markers against that grammar,
+# and a live test re-extracts from an installed binary so the fixture cannot drift
+# (it skips cleanly on a machine with no codex).
+#
+# Two deliberate differences from the real grammar, both in the safe direction:
+# codex requires the envelope's first line to be "*** Begin Patch" and its last to be
+# "*** End Patch", while this parser scans for the markers on any line of the
+# payload, not only the first and last; and "*** Environment ID:", a real production
+# of the grammar, is ignored here rather than parsed, because it names no file
+# operation. Both markers still must form a WHOLE LINE (start-of-text or a
+# preceding LF, and end-of-text or a following LF): per add_line: "+" /(.*)/ LF, a
+# content line such as "+*** End Patch" is legal file content, not a terminator, so a
+# bare substring search would misparse it as the real marker (see
+# line_anchored_index below). Anything else unparseable FAILS OPEN: parse returns []
+# and warns, so gates allow the write (orchestrator-locks fail-open rule), and the
+# PostToolUse gate-check backstop re-validates the intent file after the write
+# lands.
 module ApplyPatchEnvelope
   module_function
 
@@ -39,9 +50,11 @@ module ApplyPatchEnvelope
   # patch text by scanning for the Begin/End markers regardless of wrapping.
   def parse(command)
     text = command.is_a?(Array) ? command.join("\n") : command.to_s
-    b = text.index(BEGIN_MARK)
-    e = text.index(END_MARK)
-    return warn_empty("no Begin/End Patch markers") if b.nil? || e.nil? || e < b
+    b = line_anchored_index(text, BEGIN_MARK, 0)
+    return warn_empty("no Begin/End Patch markers") if b.nil?
+
+    e = line_anchored_index(text, END_MARK, b + BEGIN_MARK.length)
+    return warn_empty("no Begin/End Patch markers") if e.nil?
 
     body = text[(b + BEGIN_MARK.length)...e]
     ops = []
@@ -73,4 +86,24 @@ module ApplyPatchEnvelope
     $stderr.puts "plastic apply_patch parse: #{reason}; gate fails open"
     []
   end
+
+  # Finds the first occurrence of `mark` starting at or after `from` that forms a
+  # WHOLE LINE: immediately preceded by start-of-text or a newline, and immediately
+  # followed by end-of-text or a newline. A bare `text.index(mark)` would also match
+  # `mark` sitting inside a longer line, such as the content line "+*** End Patch"
+  # (legal per add_line: "+" /(.*)/ LF), which is not a terminator.
+  def line_anchored_index(text, mark, from)
+    pos = from
+    loop do
+      idx = text.index(mark, pos)
+      return nil if idx.nil?
+
+      line_start = idx.zero? || text[idx - 1] == "\n"
+      after = idx + mark.length
+      line_end = after == text.length || text[after] == "\n"
+      return idx if line_start && line_end
+
+      pos = idx + 1
+    end
+  end
 end

package/scripts/lib/bridge.rb

@@ -9,6 +9,7 @@ require "digest"
 require "socket"
 require_relative "worktree"
 require_relative "lock"
+require_relative "spec_header"
 
 module Bridge
   STAGES = %w[what why how exec done].freeze
@@ -662,13 +663,10 @@ module Bridge
   # matching the skill and agent contracts). Returns nil when spec.md is
   # absent, empty, or its first line does not match, so a missing/malformed
   # Tier line changes nothing about existing rebuild behavior.
+  # The grammar itself now lives in SpecHeader (scripts/lib/spec_header.rb, intent 213);
+  # this method is a thin read on top of it.
   def self.savepoint_tier(intent_dir)
-    path = File.join(intent_dir, "spec.md")
-    return nil unless File.exist?(path)
-    first = File.open(path, &:gets)
-    return nil if first.nil?
-    m = first.chomp.strip.match(/\ATier:\s*(S|M|L)\z/)
-    m && m[1]
+    SpecHeader.parse_file(File.join(intent_dir, "spec.md"))[:tier]
   end
 
   # Reconstruct the ledger from files on disk (timestamps from mtimes), in
@@ -767,12 +765,16 @@ module Bridge
     phantoms
   end
 
-  def self.derive(session, intent_id:, intent_dir:, store:, name:, tmp: tmp_dir)
+  # Pure compute (intent 230): build the bridge state and write NOTHING. `derive`
+  # is the writing wrapper over this; `arm` and `repair_lock` use the pure form so
+  # the single bridge write happens only after the delivery lock and the worktree
+  # have both settled. Joins the pure `derive_stage` / `derive_key` family.
+  def self.derive_data(session, intent_id:, intent_dir:, store:, name:)
     stage = derive_stage(intent_dir)
     has = has_files(intent_dir)
     missing = missing_for_stage(stage, intent_dir) - has
 
-    data = {
+    {
       "session" => session,
       "intent" => {
         "id" => intent_id,
@@ -816,7 +818,14 @@ module Bridge
         "delegates" => []
       }
     }
+  end
 
+  # Compute AND persist. Contract unchanged (intent 230 kept it deliberately):
+  # `scripts/hook-session-start` calls this and wants the immediate write, and
+  # test/bridge_worktree_derive_test.rb pins write-on-call.
+  def self.derive(session, intent_id:, intent_dir:, store:, name:, tmp: tmp_dir)
+    data = derive_data(session, intent_id: intent_id, intent_dir: intent_dir,
+                       store: store, name: name)
     write(session, data, tmp: tmp)
     data
   end
@@ -881,6 +890,19 @@ module Bridge
 
   # --- Auto mode (intent 27) ---
 
+  # Intent 230: freshly composed state carries worktree.code = nil, so a failed
+  # Worktree.provision would have nothing to keep. Seed the block from the bridge
+  # already on disk when it names a code path, so provision's keep-rule (see
+  # Worktree.provision) can preserve it. Provision SUCCESS overwrites this with
+  # the freshly resolved (identical) pointer, so this only matters on failure.
+  def self.carry_prior_worktree(data, session, tmp: tmp_dir)
+    prior = read(session, intent_id: data.dig("intent", "id"), tmp: tmp)
+    block = prior && prior["worktree"]
+    data["worktree"] = block if block.is_a?(Hash) && !blank?(block["code"])
+    data
+  end
+  private_class_method :carry_prior_worktree
+
   # 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)
@@ -893,7 +915,10 @@ module Bridge
     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)
+    # Compute only (intent 230). Nothing reaches disk until the lock is ours and
+    # the worktree has settled; a LockHeldError below must leave the previous
+    # bridge exactly as it was.
+    data = derive_data(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
     data["build"]["auto"] = auto
 
     # Acquire the durable delivery lock (D1/D2): session-keyed, O_EXCL, in the
@@ -924,6 +949,8 @@ module Bridge
         "run #{skill_ref('plastic-doctor', harness: harness)} fix the lock"
     end
 
+    carry_prior_worktree(data, key)
+
     # 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.
@@ -959,13 +986,24 @@ module Bridge
   # Degrade path for disarm_auto when no intent_id is given (intent 131): the
   # session's sole per-intent bridge when there is exactly one, else the
   # legacy single-key file. Keeps the common single-intent auto path working
-  # without every caller having to name the intent id explicitly.
+  # without every caller having to name the intent id explicitly. With TWO or
+  # more per-intent bridges it refuses to guess (intent 233); see below.
   def self.sole_bridge_data(session, tmp: tmp_dir)
     matches = Dir.glob(File.join(tmp, "plastic-#{session}--*.json")).reject { |f| f.end_with?(".tmp") }
     if matches.length == 1
       data = (JSON.parse(File.read(matches.first)) rescue nil)
       return data if data
     end
+    # Refuse to guess among siblings (intent 233): with 2+ per-intent bridges
+    # the legacy single-key file below can carry EITHER sibling, so falling
+    # through would let a no-id disarm release the wrong intent's lock. A
+    # disarm that does nothing is recoverable; one that unlocks a live
+    # delivery is not. Zero matches keeps the legacy fallback (131 migration).
+    if matches.length > 1
+      $stderr.puts "plastic: session #{session} has #{matches.length} bridges; " \
+                   "disarm needs an explicit intent_id (refusing to guess)"
+      return nil
+    end
     read(session, tmp: tmp)
   end
 
@@ -979,6 +1017,9 @@ module Bridge
   # (one per concurrent intent), so disarm must target ONE of them. When
   # intent_id is nil, degrades to the session's sole bridge (see
   # sole_bridge_data) so the common single-intent path keeps working.
+  #
+  # The lock clear is conditional (intent 233): a failed release leaves the
+  # cached lock fields alone so the orphan stays findable.
   def self.disarm_auto(session, intent_id: nil)
     data = blank?(intent_id) ? sole_bridge_data(session) : read(session, intent_id: intent_id)
     return nil unless data
@@ -994,14 +1035,39 @@ module Bridge
       $stderr.puts "plastic: worktree release raised, continuing: #{e.message}"
     end
 
+    # Check what the release actually DID before touching the cache (intent
+    # 233). Blanking the cache after a failed release orphans the durable
+    # delivery.lock: the file stays on disk and nothing points at it any more.
+    # Rescue mirrors the Worktree.release rescue above: warn, never raise,
+    # never abort the rest of the tail (the guard fails milder than the bug).
     dir = bridge_intent_dir(data)
+    release_status = nil
     if dir
       owner = data.dig("lock", "owner_session")
       owner = session if blank?(owner)
-      Lock.release(dir, session: owner)
+      begin
+        release_status = Lock.release(dir, session: owner)
+      rescue => e
+        release_status = :raised
+        $stderr.puts "plastic: delivery lock release raised for #{dir}, continuing: #{e.message}"
+      end
     end
-    data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
-                     "host" => nil, "type" => nil, "delegates" => [] }
+
+    # Success means "no lock left on disk": :released (we deleted it), :none
+    # (there was none), and nil (no intent dir, so no release was attempted).
+    # Only :not_owner and a raised release keep the cache pointing at the lock
+    # so plastic-lock fix / reclaim / doctor can still find and repair it.
+    if release_status.nil? || release_status == :released || release_status == :none
+      data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
+                       "host" => nil, "type" => nil, "delegates" => [] }
+    else
+      $stderr.puts "plastic: delivery lock NOT released for #{dir} (#{release_status}); " \
+                   "bridge lock cache preserved for repair"
+      data["lock"] = {} unless data["lock"].is_a?(Hash)
+    end
+    # Diagnostic only (D5): the primary contract stays "owner_session non-nil
+    # after disarm means the lock was not released".
+    data["lock"]["release_status"] = release_status.nil? ? nil : release_status.to_s
 
     write(session, data)
     purge_done_bridges(session: session)
@@ -1070,11 +1136,13 @@ module Bridge
       actions << "lock #{status}"
     end
 
-    data = derive(key, intent_id: intent_id, intent_dir: dir, store: store,
-                  name: name, tmp: tmp)
+    data = derive_data(key, intent_id: intent_id, intent_dir: dir, store: store,
+                       name: name)
     data["build"]["auto"] = auto
     data["lock"] = lock_cache(lock_data)
 
+    carry_prior_worktree(data, key, tmp: tmp)
+
     # Provision the per-intent worktrees so the rebuilt bridge carries
     # worktree.code (intent 136). Without it, cwd/edited-path selection has no
     # key: the repaired intent loses its own code gate and a concurrent sibling