@zalom/plastic 2.0.1 → 2.0.3

package/scripts/end-intent

@@ -34,13 +34,17 @@
 #      doctor's per-intent structure check and OutcomeGuard as a self-check
 #      that reports on stderr and proceeds. Then stamp the intent file's
 #      `## Outcome` section with --outcome-summary if given.
-#   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, 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.
+#   2. Move the intent's INDEX.md line from `## Active` or `## Future` 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,
+#      IndexEntry.match); always EMITS the real em dash on write. The move is
+#      resolved before step 1 writes anything (intent 385): an id that
+#      resolves to neither an open section nor the terminal section is a loud
+#      failure (exit 1) that writes nothing, in the dry run too; an id already
+#      correctly in the terminal section is a quiet, idempotent success. A
+#      missing INDEX.md is not a refusal: the move is skipped with a warning,
+#      and the dry run says so.
 #   3. Append the savepoint `Done` bookend (Savepoint.append_terminal_savepoint).
 #   4. Commit the store repo, unless --no-commit.
 #   5. Disarm (intent 188, D2/D16; intent 307): check the code worktree (derived
@@ -50,10 +54,15 @@
 #      the durable lock file is actually gone afterward, and release it directly
 #      when a foreign-keyed disarm left it.
 #
+# A delivered close never merges code. Its code branch must already be merged
+# into the repo checkout's current branch, or the close refuses before any
+# write (exit 9).
+#
 # Exit codes:
 #   0  ok - the intent is closed and no delivery.lock remains.
-#   1  usage/resolution failure, OR an id that resolves to neither ## Active
-#      nor the terminal section (D11). Deliberately double duty; see plan.md.
+#   1  usage/resolution failure, OR an id that resolves to neither ## Active,
+#      ## Future, nor the terminal section (D11). Deliberately double duty;
+#      see plan.md. Refused before any write.
 #   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 (see step 5 above).
@@ -67,13 +76,27 @@
 #   6  retired in 2.0 (intent 308): the structure check reports and proceeds.
 #   7  hollow delivered report refused (317a D7) - intent 308's one deliberate
 #      exception to report-and-proceed; --allow-hollow-report overrides.
+#   8  delivered close of an untouched scaffold refused (acceptance N3):
+#      nothing was worked, so there is nothing to deliver. Close it as
+#      abandoned, or do the work first. Authors nothing.
+#   9  delivered close refused because its code branch is not merged into the
+#      repo checkout's current branch. Refused before any write: nothing is
+#      merged, written, or released. Merge the branch, then run the close again.
+#
+# --dry-run runs the same refusals as the real close (exits 1, 8, 9, 7 and 5 with
+# a "would refuse" line) and writes nothing: the hollow-report gate is judged
+# on a scratch copy that went through the same outcome generation and
+# backfill.
 
 require_relative "lib/store_layout"
 require "fileutils"
 require "date"
 require "open3"
+require "stringio"
+require "tmpdir"
 require "pathname"
 require_relative "lib/arm"
+require_relative "lib/exec_worktree"
 require_relative "lib/index_entry"
 require_relative "lib/savepoint"
 require_relative "lib/lock"
@@ -82,6 +105,8 @@ require_relative "lib/outcome_guard"
 require_relative "lib/report_screen"
 require_relative "lib/backfill_intent"
 require_relative "lib/outcome_report"
+require_relative "lib/untouched_scaffold"
+require_relative "lib/scaffold_intent"
 
 DISPOSITIONS = %w[delivered abandoned].freeze
 
@@ -93,10 +118,15 @@ DISPOSITIONS = %w[delivered abandoned].freeze
 # (intent 188, D9/D12): see move_index_to_terminal below.
 EM_DASH = "\u2014"
 
-# Raised internally when the INDEX id resolves to neither `## Active` nor the
-# terminal section (D11): the caller (main) rescues this and exits 1.
+# Raised internally when the INDEX id resolves to neither an open section nor
+# the terminal section (D11): the caller (main) rescues this and exits 1.
 class UnresolvedIndexEntry < StandardError; end
 
+# The INDEX sections an intent can still be closed from, searched in order
+# (intent 385): a Future intent is retired through the same path as an
+# Active one.
+OPEN_HEADINGS = ["## Active", "## Future"].freeze
+
 # --- Explicit flag parsing (no eval, no global injection) -------------------
 
 def blank?(value)
@@ -447,19 +477,32 @@ def section_contains_id?(lines, heading_idx, id)
   (heading_idx + 1...stop).any? { |i| active_line_id(lines[i]) == id }
 end
 
-# Remove the entry at entry_idx from the `## Active` section. When no real
+# The first open section holding the id's entry, as [heading, heading_idx,
+# entry_idx], or nil when no open section holds it.
+def find_open_entry(lines, id)
+  OPEN_HEADINGS.each do |heading|
+    start = lines.index { |l| l.rstrip == heading }
+    next unless start
+
+    entry_idx = (start + 1...section_stop(lines, start)).find { |i| active_line_id(lines[i]) == id }
+    return [heading, start, entry_idx] if entry_idx
+  end
+  nil
+end
+
+# Remove the entry at entry_idx from its open section. When no real
 # entries remain, install the canonical "_(none)_" placeholder (the same
 # empty-state convention INDEX.md already uses).
-def remove_active_entry(lines, active_start, entry_idx)
+def remove_open_entry(lines, section_start, entry_idx)
   new_lines = lines.dup
   new_lines.delete_at(entry_idx)
-  stop = section_stop(new_lines, active_start)
-  remaining = (active_start + 1...stop).reject { |i| new_lines[i].strip.empty? }
+  stop = section_stop(new_lines, section_start)
+  remaining = (section_start + 1...stop).reject { |i| new_lines[i].strip.empty? }
   if remaining.empty?
     # Keep the blank-line separator before the next heading (if any); only
     # collapse the section body to the placeholder, never the spacing.
     placeholder = (stop < new_lines.length) ? ["_(none)_\n", "\n"] : ["_(none)_\n"]
-    new_lines[(active_start + 1)...stop] = placeholder
+    new_lines[(section_start + 1)...stop] = placeholder
   end
   new_lines
 end
@@ -483,34 +526,30 @@ def insert_terminal_entry(lines, target_start, new_entry)
   new_lines
 end
 
-# Move the intent's `## Active` line into the terminal section. Returns the
-# new INDEX.md content on success. Raises UnresolvedIndexEntry (D11) when the
-# id resolves to NEITHER `## Active` NOR the terminal section (including the
-# degenerate case where one of the two headings is missing from INDEX.md
-# entirely); returns the content UNCHANGED (a quiet, idempotent success) when
-# the id is already correctly present in the terminal section, whether or not
-# a stray duplicate also still sits under `## Active` (that duplicate is
-# cleaned up too, when found, matching the pre-188 idempotent-cleanup
-# behavior for the ordinary already-moved re-run case).
+# Move the intent's `## Active` or `## Future` line into the terminal
+# section. Returns the new INDEX.md content on success. Raises
+# UnresolvedIndexEntry (D11) when the id resolves to NEITHER an open section
+# NOR the terminal section (including the degenerate case where the headings
+# are missing from INDEX.md entirely); returns the content UNCHANGED (a quiet,
+# idempotent success) when the id is already correctly present in the
+# terminal section, whether or not a stray duplicate also still sits in an
+# open section (that duplicate is cleaned up too, when found, matching the
+# pre-188 idempotent-cleanup behavior for the ordinary already-moved re-run
+# case).
 def move_index_to_terminal(content, id, disposition, today:, index_note: nil)
   target_heading = index_target_heading(disposition)
   lines = content.lines
 
   target_start = lines.index { |l| l.rstrip == target_heading }
-  active_start = lines.index { |l| l.rstrip == "## Active" }
   already_in_target = target_start && section_contains_id?(lines, target_start, id)
 
-  entry_idx = nil
-  if active_start
-    active_stop = section_stop(lines, active_start)
-    entry_idx = (active_start + 1...active_stop).find { |i| active_line_id(lines[i]) == id }
-  end
+  _heading, source_start, entry_idx = find_open_entry(lines, id)
 
   if entry_idx.nil?
     return content if already_in_target # true idempotency (D11): quiet success
     raise UnresolvedIndexEntry,
-          "intent #{id} could not be resolved: not found under ## Active, and not already " \
-          "present in #{target_heading} (check INDEX.md for a malformed or missing entry)"
+          "intent #{id} could not be resolved: not found under #{OPEN_HEADINGS.join(" or ")}, and not " \
+          "already present in #{target_heading} (check INDEX.md for a malformed or missing entry)"
   end
 
   if target_start.nil?
@@ -522,7 +561,7 @@ def move_index_to_terminal(content, id, disposition, today:, index_note: nil)
   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"
 
-  lines = remove_active_entry(lines, active_start, entry_idx)
+  lines = remove_open_entry(lines, source_start, entry_idx)
   target_start = lines.index { |l| l.rstrip == target_heading }
   lines = insert_terminal_entry(lines, target_start, new_entry) unless already_in_target
 
@@ -543,7 +582,27 @@ def warn_if_active_duplicate_remains(content, id)
 
   warn "end-intent: intent #{id} still has an entry under ## Active after the move " \
        "(a duplicate ## Active line for this id); INDEX.md needs manual cleanup. Check " \
-       "INDEX.md directly, or run /plastic-doctor."
+       "INDEX.md directly, or run `plastic doctor`."
+end
+
+# The dry-run line for the INDEX move the close will make, resolved on the
+# current INDEX.md before anything is written (intent 385), so the preview
+# and the real close refuse the same unresolvable entry. Exits 1 on
+# UnresolvedIndexEntry, exactly as step 2 would, but before step 1 writes.
+def preflight_index_move(index_path, id, disposition, today:, index_note:)
+  target = index_target_heading(disposition)
+  return "INDEX.md not found at #{index_path}, would skip the terminal move" unless File.exist?(index_path)
+
+  content = File.read(index_path)
+  move_index_to_terminal(content, id, disposition, today: today, index_note: index_note)
+  source, = find_open_entry(content.lines, id)
+  return "INDEX.md entry already in #{target}, would leave it (#{index_path})" unless source
+
+  "would move INDEX.md entry from #{source} to #{target} (#{index_path})"
+rescue UnresolvedIndexEntry => e
+  warn "end-intent: #{e.message}"
+  warn "end-intent: nothing was written"
+  exit 1
 end
 
 # --- store auto-commit (D2 step 4) ------------------------------------------
@@ -665,32 +724,10 @@ def run_disarm(intent_dir, id, session, discard_worktree_changes:,
   block = worktree_reader.call(intent_dir)
   worktree_code = block.is_a?(Hash) ? block["code"] : nil
 
-  if worktree_code && Dir.exist?(worktree_code)
-    begin
-      out, err, status = Open3.capture3("git", "-C", worktree_code, "status", "--porcelain")
-    rescue StandardError => e
-      out, err, status = nil, e.message, nil
-    end
-
-    # Fail CLOSED (intent 188, post-review hardening). A failed or impossible
-    # `git status` (corrupt per-worktree index, git missing from PATH, not a
-    # repo) means we cannot PROVE the worktree is clean, and the removal below
-    # force-removes on a plain `git worktree remove` failure, which destroys
-    # uncommitted work. Never force-remove an unproven worktree: the guard
-    # exists to protect uncommitted code, so an inconclusive check must refuse,
-    # not silently proceed as if it were clean.
-    if status.nil? || !status.success?
-      unless discard_worktree_changes
-        warn "end-intent: could not inspect the code worktree at #{worktree_code} " \
-             "(git status failed: #{err.to_s.strip}); refusing to remove it, because " \
-             "removal would force-discard any uncommitted work. Pass " \
-             "--discard-worktree-changes to remove it anyway, or repair the worktree."
-        return :dirty
-      end
-    elsif !out.strip.empty? && !discard_worktree_changes
-      warn "end-intent: code worktree #{worktree_code} has uncommitted changes; refusing " \
-           "to remove it. Pass --discard-worktree-changes to force the close deliberately, " \
-           "or commit/stash the changes and re-run."
+  unless discard_worktree_changes
+    refusal = worktree_refusal(worktree_code)
+    if refusal
+      warn refusal
       return :dirty
     end
   end
@@ -733,7 +770,7 @@ def run_disarm(intent_dir, id, session, discard_worktree_changes:,
         # let the caller sort it out.
         warn "end-intent: the delivery lock at #{Lock.path(intent_dir)} is now held by " \
              "#{current['owner_session'].inspect}, which acquired it during this close; " \
-             "refusing to delete another session's lock. Run /plastic-doctor to check the " \
+             "refusing to delete another session's lock. Run `plastic doctor` to check the " \
              "lock status."
       end
       # current.nil? here means the lock is corrupt/unparseable; nothing to
@@ -748,16 +785,183 @@ def run_disarm(intent_dir, id, session, discard_worktree_changes:,
     if block.nil?
       warn "end-intent: no worktree block could be derived for intent #{id}; " \
            "the delivery lock was cleared directly from disk, but any worktree this intent " \
-           "provisioned was NOT removed. Run /plastic-doctor to check for an orphaned worktree."
+           "provisioned was NOT removed. Run `plastic doctor` to check for an orphaned worktree."
     end
     return :ok
   end
 
   warn "end-intent: the delivery lock at #{Lock.path(intent_dir)} is still present after " \
-       "disarm and a direct release attempt. Run /plastic-doctor to check the lock status."
+       "disarm and a direct release attempt. Run `plastic doctor` to check the lock status."
   :lock_remains
 end
 
+# The disarm step's dirty-worktree guard, as a message (nil when the worktree
+# is clean or absent). Shared by run_disarm and --dry-run so the preview
+# refuses exactly what the close refuses.
+#
+# Fail CLOSED (intent 188, post-review hardening). A failed or impossible
+# `git status` (corrupt per-worktree index, git missing from PATH, not a
+# repo) means we cannot PROVE the worktree is clean, and the removal
+# force-removes on a plain `git worktree remove` failure, which destroys
+# uncommitted work. Never force-remove an unproven worktree: the guard
+# exists to protect uncommitted code, so an inconclusive check must refuse,
+# not silently proceed as if it were clean.
+def worktree_refusal(worktree_code)
+  return nil unless worktree_code && Dir.exist?(worktree_code)
+
+  begin
+    out, err, status = Open3.capture3("git", "-C", worktree_code, "status", "--porcelain")
+  rescue StandardError => e
+    out, err, status = nil, e.message, nil
+  end
+
+  if status.nil? || !status.success?
+    "end-intent: could not inspect the code worktree at #{worktree_code} " \
+      "(git status failed: #{err.to_s.strip}); refusing to remove it, because " \
+      "removal would force-discard any uncommitted work. Pass " \
+      "--discard-worktree-changes to remove it anyway, or repair the worktree."
+  elsif !out.strip.empty?
+    "end-intent: code worktree #{worktree_code} has uncommitted changes; refusing " \
+      "to remove it. Pass --discard-worktree-changes to force the close deliberately, " \
+      "or commit/stash the changes and re-run."
+  end
+end
+
+# True when the intent's code worktree carries any work: uncommitted changes
+# or commits past its base branch. Anything that cannot be proven reads as
+# changed, so an unreadable worktree never turns a close into a refusal.
+def worktree_changed?(intent_dir)
+  block = Arm.worktree_block(intent_dir: intent_dir)
+  code = block.is_a?(Hash) ? block["code"] : nil
+  return false unless code && Dir.exist?(code)
+
+  out, status = Open3.capture2e("git", "-C", code, "status", "--porcelain")
+  return true unless status.success? && out.strip.empty?
+
+  base = ScaffoldIntent.detect_base_branch(code)
+  return true if base.nil?
+
+  ahead, status = Open3.capture2e("git", "-C", code, "rev-list", "--count", "#{base}..HEAD")
+  !status.success? || ahead.strip != "0"
+rescue StandardError
+  true
+end
+
+# A delivered close whose code is not on the repo checkout's current branch,
+# as a refusal message (nil when it is, or for a store-only project).
+# end-intent never merges: the owner merges or releases the work, then runs
+# the close again. A real code worktree must prove that its HEAD commit is
+# merged, so a detached or renamed branch is still checked. The code branch
+# must be merged too, even after its worktree is gone. A git failure refuses.
+# A directory that is not a working git worktree, with no code branch, is left
+# to the dirty-worktree guard, which refuses what it cannot inspect.
+def unmerged_refusal(intent_dir, runner: Worktree::ShellRunner.new)
+  paths = Arm.code_paths(intent_dir: intent_dir)
+  code = paths["code"]
+  return nil if code.nil?
+
+  repo = ExecWorktree.repo_from_worktree_code(code)
+  unless runner.run("-C", repo, "rev-parse", "--git-dir").success?
+    # No .git at all is a project without code; a .git that Git cannot read is not.
+    return nil unless File.exist?(File.join(repo, ".git"))
+
+    return "could not inspect the Git repository #{repo}, so the code cannot be shown to be merged. " \
+      "Check the repository, then run the close again"
+  end
+
+  unmerged_worktree_head(runner, code, repo, paths["code_branch"]) ||
+    unmerged_branch(runner, repo, paths["code_branch"])
+end
+
+# True when `code` is the top of its own git work tree, not a plain
+# directory inside the repo or a broken checkout.
+def real_worktree?(runner, code)
+  return false unless File.directory?(code)
+
+  top = runner.run("-C", code, "rev-parse", "--show-toplevel")
+  top.success? && File.realpath(top.stdout.strip) == File.realpath(code)
+rescue SystemCallError
+  false
+end
+
+def unmerged_worktree_head(runner, code, repo, branch)
+  return nil unless real_worktree?(runner, code)
+
+  head = runner.run("-C", code, "rev-parse", "--verify", "--quiet", "HEAD^{commit}")
+  unless head.success?
+    return "could not read the HEAD commit of the code worktree #{code}, so its work cannot be " \
+      "shown to be merged. Commit it, merge it into the current branch of #{repo}, then run the close again"
+  end
+  sha = head.stdout.strip
+  on = runner.run("-C", code, "symbolic-ref", "--quiet", "--short", "HEAD")
+  name = on.success? ? on.stdout.strip : nil
+  ref = (name == branch) ? branch : sha[0, 12]
+  where = name ? "on branch #{name}" : "detached"
+  ancestry_refusal(runner, repo, sha, ref, "the code worktree #{code} (#{where} at #{sha[0, 12]})", branch)
+end
+
+def unmerged_branch(runner, repo, branch)
+  found = runner.run("-C", repo, "show-ref", "--verify", "--quiet", "refs/heads/#{branch}")
+  return nil if found.status == 1
+  unless found.success?
+    return "could not look up code branch #{branch} in #{repo}. Check the repository, then run the close again"
+  end
+  ancestry_refusal(runner, repo, branch, branch, "code branch #{branch}", branch)
+end
+
+# nil when `rev` is an ancestor of the branch the repo checkout is on, else a
+# refusal naming `what` and the ordinary merge of `ref` that fixes it.
+def ancestry_refusal(runner, repo, rev, ref, what, branch)
+  target = target_refusal(runner, repo, branch)
+  return target if target
+
+  check = runner.run("-C", repo, "merge-base", "--is-ancestor", rev, "HEAD")
+  return nil if check.success?
+
+  verdict = (check.status == 1) ? "is not merged into" : "could not be checked against"
+  "#{what} #{verdict} the current branch of #{repo}. " \
+    "Merge it there first (git -C #{repo} merge #{ref}), then run the close again"
+end
+
+# Integration means merged into a branch other than the code branch, so a
+# detached checkout, or one on the code branch itself, proves nothing.
+def target_refusal(runner, repo, branch)
+  on = runner.run("-C", repo, "symbolic-ref", "--quiet", "--short", "HEAD")
+  unless on.success?
+    return "the repo checkout #{repo} is not on a branch, so no branch holds the merged code. " \
+      "Check out the branch you release from, merge #{branch} into it, then run the close again"
+  end
+  return nil unless on.stdout.strip == branch
+
+  "the repo checkout #{repo} is on the code branch #{branch} itself, so the code is not merged anywhere. " \
+    "Check out the branch you release from, merge #{branch} into it, then run the close again"
+end
+
+# The hollow-report verdict the real close would reach, judged on a scratch
+# copy of the intent after the same outcome generation and backfill, so the
+# dry run writes nothing.
+def predicted_hollow_reason(intent_dir, store:, id:, disposition:, summary:)
+  return nil unless disposition == "delivered"
+
+  Dir.mktmpdir("end-intent-dry-run") do |scratch|
+    copy = File.join(scratch, File.basename(intent_dir))
+    FileUtils.cp_r(intent_dir, copy)
+    quietly do
+      run_generate_outcome(copy, disposition: disposition)
+      run_backfill(copy, store: store, id: id, disposition: disposition, summary: summary)
+    end
+    hollow_report_reason(copy, disposition)
+  end
+end
+
+def quietly
+  saved = $stderr
+  $stderr = StringIO.new
+  yield
+ensure
+  $stderr = saved
+end
+
 # --- main --------------------------------------------------------------------
 
 def main(argv)
@@ -789,7 +993,7 @@ def main(argv)
     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 " \
-         "--session explicitly, or run /plastic-doctor check the lock status."
+         "--session explicitly, or run `plastic doctor` to check the lock status."
     exit 4
   end
 
@@ -797,7 +1001,7 @@ def main(argv)
 
   if verdict == :refuse
     warn "end-intent: delivery lock for #{id} is held by a live session " \
-         "(#{lock_data['owner_session']}); refusing to close. Run /plastic-doctor check " \
+         "(#{lock_data['owner_session']}); refusing to close. Run `plastic doctor` to check " \
          "the lock status"
     exit 4
   end
@@ -805,17 +1009,56 @@ def main(argv)
   if verdict == :refuse_corrupt
     warn "end-intent: the delivery lock at #{Lock.path(intent_dir)} exists and is fresh, " \
          "but its content will not parse (corrupt); refusing to close since another " \
-         "session may be actively heartbeating it. Run /plastic-doctor check the lock " \
+         "session may be actively heartbeating it. Run `plastic doctor` to check the lock " \
          "status, or plastic-lock fix once it is confirmed safe."
     exit 4
   end
 
+  # Nothing worked, nothing to deliver (acceptance N3). Before the dry run and
+  # before any write, so the preview and the close refuse together.
+  if disposition == "delivered"
+    untouched = UntouchedScaffold.reason(intent_dir, templates: BackfillIntent.load_templates,
+                                                     worktree_changed: method(:worktree_changed?))
+    if untouched
+      warn "end-intent: refusing to deliver an untouched scaffold: #{untouched}"
+      warn "end-intent: do the work first, or close it with --disposition abandoned"
+      exit 8
+    end
+
+    unmerged = unmerged_refusal(intent_dir)
+    if unmerged
+      warn "end-intent: #{opts[:dry_run] ? "dry run: would refuse" : "refusing"} a delivered close: #{unmerged}"
+      warn "end-intent: nothing was merged, written, or released"
+      exit 9
+    end
+  end
+
+  # Resolve the INDEX move before any write (intent 385), in the dry run and the
+  # real close alike: an entry the move cannot find refuses here, not after the
+  # backfill has already written into the intent directory.
+  index_move = preflight_index_move(index_path, id, disposition, today: today, index_note: opts[:index_note])
+
   if opts[:dry_run]
+    hollow = predicted_hollow_reason(intent_dir, store: store, id: id, disposition: disposition,
+                                                 summary: opts[:outcome_summary])
+    if hollow && !opts[:allow_hollow_report]
+      warn "end-intent: dry run: would refuse a hollow delivered close: #{hollow}"
+      exit 7
+    end
+    unless blank?(session) || opts[:discard_worktree_changes]
+      block = Arm.worktree_block(intent_dir: intent_dir)
+      refusal = worktree_refusal(block.is_a?(Hash) ? block["code"] : nil)
+      if refusal
+        warn "end-intent: dry run: would refuse at disarm (exit 5), after the store commit: " \
+             "#{refusal.delete_prefix("end-intent: ")}"
+        exit 5
+      end
+    end
     puts "end-intent: dry run for #{File.basename(intent_dir)} (#{disposition})"
     targets = BackfillIntent.targets_for(intent_dir)
     puts "  would backfill: #{targets.empty? ? "(nothing)" : targets.join(", ")}"
     puts "  would stamp ## Outcome: #{opts[:outcome_summary].inspect}" if opts[:outcome_summary]
-    puts "  would move INDEX.md entry from ## Active to #{index_target_heading(disposition)} (#{index_path})"
+    puts "  #{index_move}"
     puts "  would append index note: #{opts[:index_note].inspect}" if opts[:index_note]
     puts "  would append savepoint bookend: Done  #{disposition}"
     puts(opts[:no_commit] ? "  would skip store commit (--no-commit)" : "  would commit the store repo")
@@ -831,7 +1074,7 @@ def main(argv)
     takeover_status, = Lock.takeover(intent_dir, session: session)
     unless takeover_status == :taken
       warn "end-intent: could not take over the stale delivery lock for #{id} " \
-           "(status: #{takeover_status}); run /plastic-doctor fix the lock"
+           "(status: #{takeover_status}); run `plastic doctor` to inspect the lock"
       exit 4
     end
   end

package/scripts/lib/arm.rb

@@ -81,12 +81,7 @@ module Arm
   # `{code, code_branch, provisioned}` derived from projects.yml and the
   # intent id: the same path provision creates, `provisioned` iff it exists.
   def worktree_block(intent_dir:, home: Dir.home)
-    dir = File.expand_path(intent_dir)
-    store = store_for(dir)
-    h = home_for(dir, home: home)
-    slug = Worktree.slug_for_store(store, home: h)
-    p = Worktree.paths(slug: slug, intent_id: intent_id_for(dir),
-                       intent_slug: Worktree.slug_from_dir(dir), home: h)
+    p = code_paths(intent_dir: intent_dir, home: home)
     code = p["code"]
     provisioned = !blank?(code) && Dir.exist?(code)
     {
@@ -96,6 +91,16 @@ module Arm
     }
   end
 
+  # The code worktree path and branch this intent would have, whether or not
+  # the worktree exists on disk (blank code for a store-only project).
+  def code_paths(intent_dir:, home: Dir.home)
+    dir = File.expand_path(intent_dir)
+    h = home_for(dir, home: home)
+    slug = Worktree.slug_for_store(store_for(dir), home: h)
+    Worktree.paths(slug: slug, intent_id: intent_id_for(dir),
+                   intent_slug: Worktree.slug_from_dir(dir), home: h)
+  end
+
   # Owner rule 2026-08-31: has this session already started a conversation?
   # A conversation session's tmp directory is made at boot under the global
   # store's `.tmp/`; a dispatched or headless session (a derived key) never
@@ -182,13 +187,19 @@ module Arm
 
   # --- repair ------------------------------------------------------------------
 
+  # A stale foreign lock is reclaimed only by an audited owner step, never by
+  # the session that found it.
+  def stale_hint(intent_id)
+    "reclaiming a stale lock is the owner's audited step; plastic auto lock status #{intent_id} shows it"
+  end
+
   # One idempotent repair (the lock half of the repair path):
   # remove a corrupt lock, back off from a fresh foreign lock (`held`), report
   # a stale foreign lock (`stale`) for the explicit reclaim verb, keep and
   # enrich an own lock, heartbeat a delegated one, acquire when none, and
   # provision the worktree so the repaired intent has its checkout.
   def repair(intent_dir:, session:, home: Dir.home, now: Time.now, harness: nil,
-             agent: nil, model: nil, thread: nil, run_mode: nil, hint_harness: nil,
+             agent: nil, model: nil, thread: nil, run_mode: nil,
              runner: Worktree::ShellRunner.new)
     dir = File.expand_path(intent_dir)
     h = home_for(dir, home: home)
@@ -208,11 +219,18 @@ module Arm
       end
       return { "status" => "stale", "owner" => lock["owner_session"],
                "actions" => actions, "session" => key,
-               "hint" => "run #{Lock.skill_ref('plastic-doctor', harness: hint_harness || harness)} " \
-                         "reclaim the lock to take over with an audit" }
+               "hint" => stale_hint(intent_id_for(dir)) }
     end
 
-    mode = blank?(run_mode) ? (lock && lock["run_mode"]) : run_mode.to_s
+    # A lock rebuilt from nothing (none, or a corrupt one removed) is an auto
+    # delivery's lock again; a kept lock keeps whatever mode it had.
+    mode = if !blank?(run_mode)
+      run_mode.to_s
+    elsif lock
+      lock["run_mode"]
+    else
+      "auto"
+    end
     if lock
       if lock["owner_session"].to_s == key.to_s
         lock_data = lock.dup

package/scripts/lib/cli/commands/auto_lock.rb

@@ -9,8 +9,9 @@ require_relative "../legacy"
 # Legacy). The verb comes first, then the id, since the verb is what the
 # table's two-token match consumes as part of the command name.
 #
-# `status` speaks JSON, so this command renders it as a screen and leaves the
-# document to `--json`. `fix` and `release` already report in prose.
+# `status` and `fix` speak JSON, so this command renders them as a screen and
+# leaves the document to `--json`. `release` already reports in prose. A lock
+# another session owns exits 3, which travels as a refusal.
 module Plastic
   class CLI
     module Commands
@@ -32,7 +33,11 @@ module Plastic
         def call
           raise Usage, "VERB must be one of #{VERBS.join(", ")}" unless VERBS.include?(verb)
 
-          (verb == "status") ? screen(report) : run_verb
+          case verb
+          when "status" then screen(report("status"))
+          when "fix" then options[:json] ? run_verb : fix_screen(report("fix"))
+          else run_verb
+          end
           @output.next_step(AFTER.fetch(verb).sub("ID", id.to_s), because: BECAUSE.fetch(verb))
         end
 
@@ -43,8 +48,8 @@ module Plastic
           raise Failure, "plastic-lock exited #{status}" unless status.zero?
         end
 
-        def report
-          text, status = legacy.capture("plastic-lock", "status", "--intent-dir", intent_dir)
+        def report(name)
+          text, status = legacy.capture("plastic-lock", name, "--intent-dir", intent_dir)
           raise Failure, "plastic-lock exited #{status}" unless status.zero?
 
           JSON.parse(text)
@@ -60,6 +65,13 @@ module Plastic
           @output.row("claims", Array(report["claims"]).map(&:to_s))
         end
 
+        def fix_screen(report)
+          lock = report["lock"] || {}
+          @output.row("lock", "#{report["status"]} by #{lock["owner_session"] || report["session"]}, " \
+                              "#{lock["run_mode"]} mode")
+          @output.row("actions", Array(report["actions"]).map(&:to_s))
+        end
+
         def lock_line(report)
           lock = report["lock"]
           return "corrupt, plastic auto lock fix #{id} rewrites it" if report["lock_corrupt"]