@zalom/plastic 1.0.0-beta.24 → 1.0.0-beta.26

package/scripts/lib/installer_core.rb

@@ -6,6 +6,7 @@ require "yaml"
 require "fileutils"
 require "digest"
 require "time"
+require_relative "hook_registry"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/versions) and their tests can run
@@ -214,6 +215,10 @@ class InstallerCore
       "scripts/lib/retrieval_gate.rb" => "scripts/lib/retrieval_gate.rb",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
+      "scripts/plastic-lock" => "scripts/plastic-lock",
+      "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
+      "scripts/agent-report" => "scripts/agent-report",
       "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
       "scripts/lib/worktree.rb" => "scripts/lib/worktree.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
@@ -540,68 +545,9 @@ class InstallerCore
 
     purge_stale_plastic_hooks(hooks)
 
-    plastic_hooks = {
-      "SessionStart" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-session-start", "statusMessage" => "Loading Plastic context..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-check-update", "statusMessage" => "" },
-        ],
-      },
-      "PreCompact" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-savepoint", "statusMessage" => "Saving Plastic intent state..." },
-        ],
-      },
-      # PreToolUse carries TWO plastic groups with distinct matchers: the
-      # code-gate (Write|Edit|NotebookEdit) and the create-gate (Write only, intent
-      # 60b). A single group cannot carry two matchers, so this event maps to a
-      # LIST of groups; the merge loop appends each (idempotent because the purge
-      # pass removes all prior plastic groups first).
-      "PreToolUse" => [
-        {
-          "matcher" => "Write|Edit|NotebookEdit",
-          "hooks" => [
-            { "type" => "command", "command" => "#{hook_dir}/plastic-code-gate", "statusMessage" => "Checking lifecycle gate..." },
-            # Fail-closed lock gate (intent 96): a 2nd ordered command INSIDE the
-            # code-gate group (NOT a new same-matcher group, which the merge loop
-            # below would collapse). Blocks no-lock writes to an active intent's dir.
-            { "type" => "command", "command" => "#{hook_dir}/plastic-lock-gate", "statusMessage" => "Checking lock gate..." },
-          ],
-        },
-        {
-          "matcher" => "Write",
-          "hooks" => [
-            { "type" => "command", "command" => "#{hook_dir}/plastic-create-gate", "statusMessage" => "Checking create gate..." },
-          ],
-        },
-        # Retrieval gate (intent 84, Lever 2): redirects store-markdown reads to
-        # QMD and code reads to Serena when those tools are present. Binds the
-        # main agent AND subagents (PreToolUse applies to subagent tool calls).
-        {
-          "matcher" => "Bash|Read|Grep|Glob",
-          "hooks" => [
-            { "type" => "command", "command" => "#{hook_dir}/plastic-retrieval-gate", "statusMessage" => "Checking retrieval gate..." },
-          ],
-        },
-      ],
-      "PostToolUse" => {
-        "matcher" => "Write|Edit",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-gate-check", "statusMessage" => "Checking lifecycle gates..." },
-        ],
-      },
-      "UserPromptSubmit" => {
-        "matcher" => "",
-        "hooks" => [
-          { "type" => "command", "command" => "#{hook_dir}/plastic-continue", "statusMessage" => "Checking for continue..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-future-intent-check", "statusMessage" => "Checking future intents..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-auto-arm", "statusMessage" => "Checking auto mode..." },
-          { "type" => "command", "command" => "#{hook_dir}/plastic-qmd-search", "statusMessage" => "Searching QMD..." },
-        ],
-      },
-    }
+    # Single source of truth (intent 108, D7): registrations live in
+    # HookRegistry; this merge only translates them into settings.json.
+    plastic_hooks = HookRegistry.claude_settings_hooks(hook_dir: hook_dir)
 
     plastic_hooks.each do |event, group|
       hooks[event] ||= []

package/scripts/lib/lock.rb

@@ -0,0 +1,193 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "socket"
+require "time"
+
+# Lock: the durable single-owner delivery lock (intent 108).
+#
+# One JSON lock file per intent, delivery.lock, living IN the intent dir beside
+# savepoint.md (git-ignored, transient state). Ownership is session-keyed (D1):
+# the file records the owner session, never a pid. Liveness is a lease: the
+# owner's hooks touch the file mtime on tool calls (heartbeat); the lock is
+# stale only when that heartbeat is older than the TTL. The /tmp bridge is a
+# per-session CACHE of this state; on any disagreement the lock file wins (D2).
+#
+# Mutual-exclusion seam (D3): the schema carries a type ("delivery" now,
+# "maintenance" in a chained intent after 93) and acquire refuses while the
+# OTHER type is fresh. Only the seam ships in 108.
+#
+# Pure and dependency-injected: every function takes explicit paths plus ttl:
+# and now:; nothing here reads ENV or globals, and nothing shells out.
+module Lock
+  module_function
+
+  TYPES = %w[delivery maintenance].freeze
+
+  # Lease TTL. Heartbeats fire from the write-path hooks (PostToolUse
+  # gate-check and the lock-gate allow path), so a delivering session
+  # refreshes constantly; 30 minutes tolerates long read-only stretches
+  # without opening a takeover window mid-delivery. Reclaim is explicit
+  # either way (takeover), so the TTL only bounds WHEN takeover is allowed.
+  TTL_SECONDS = 1800
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  def path(intent_dir, type: "delivery")
+    File.join(intent_dir, "#{type}.lock")
+  end
+
+  # Parsed lock Hash, or nil when absent or corrupt (corrupt? distinguishes).
+  def read(intent_dir, type: "delivery")
+    p = path(intent_dir, type: type)
+    return nil unless File.exist?(p)
+    data = JSON.parse(File.read(p)) rescue nil
+    data.is_a?(Hash) ? data : nil
+  end
+
+  def corrupt?(intent_dir, type: "delivery")
+    File.exist?(path(intent_dir, type: type)) && read(intent_dir, type: type).nil?
+  end
+
+  # Lease freshness: the file mtime IS the heartbeat.
+  def fresh?(intent_dir, type: "delivery", ttl: TTL_SECONDS, now: Time.now)
+    p = path(intent_dir, type: type)
+    return false unless File.exist?(p)
+    (now - File.mtime(p)) <= ttl
+  end
+
+  # session is the owner or a registered delegate (D4).
+  def authorized?(data, session)
+    return false unless data.is_a?(Hash)
+    return false if blank?(session)
+    return true if data["owner_session"].to_s == session.to_s
+    Array(data["delegates"]).map(&:to_s).include?(session.to_s)
+  end
+
+  # The one question gates ask: does session hold this intent's lock?
+  # Owner/delegate on an EXISTING lock counts even when stale (a stale lock is
+  # still theirs until an explicit takeover replaces it); freshness only
+  # guards AGAINST other sessions.
+  def holds?(intent_dir, session:, type: "delivery")
+    authorized?(read(intent_dir, type: type), session)
+  end
+
+  # Atomic acquisition (O_EXCL). Returns a [status, data] pair:
+  #   [:acquired, lock]  created fresh
+  #   [:owned, lock]     re-acquire by the current owner (idempotent re-arm)
+  #   [:held, lock]      fresh foreign lock: back off
+  #   [:stale, lock]     expired foreign lock: explicit takeover required
+  #   [:excluded, other] the OTHER lock type is fresh (D3)
+  #   [:corrupt, nil]    unparseable lock file: run repair
+  def acquire(intent_dir, session:, type: "delivery", host: Socket.gethostname,
+              ttl: TTL_SECONDS, now: Time.now)
+    raise ArgumentError, "unknown lock type #{type.inspect}" unless TYPES.include?(type)
+    raise ArgumentError, "lock session must be present" if blank?(session)
+
+    other = (TYPES - [type]).first
+    if fresh?(intent_dir, type: other, ttl: ttl, now: now)
+      return [:excluded, read(intent_dir, type: other)]
+    end
+
+    return [:corrupt, nil] if corrupt?(intent_dir, type: type)
+
+    existing = read(intent_dir, type: type)
+    if existing
+      if existing["owner_session"].to_s == session.to_s
+        data = payload(session: session, type: type, host: host, now: now,
+                       delegates: Array(existing["delegates"]))
+        write(intent_dir, data, type: type)
+        return [:owned, data]
+      end
+      return [:held, existing] if fresh?(intent_dir, type: type, ttl: ttl, now: now)
+      return [:stale, existing]
+    end
+
+    data = payload(session: session, type: type, host: host, now: now)
+    File.open(path(intent_dir, type: type),
+              File::WRONLY | File::CREAT | File::EXCL) do |io|
+      io.write(JSON.pretty_generate(data))
+    end
+    [:acquired, data]
+  rescue Errno::EEXIST
+    [:held, read(intent_dir, type: type)] # lost the O_EXCL race
+  end
+
+  def payload(session:, type:, host:, now:, delegates: [])
+    {
+      "type" => type,
+      "owner_session" => session.to_s,
+      "host" => host,
+      "acquired_at" => now.utc.iso8601,
+      "delegates" => delegates,
+    }
+  end
+
+  # Owner/delegate heartbeat: touch the mtime, never rewrite content.
+  def heartbeat(intent_dir, session:, type: "delivery", now: Time.now)
+    return false unless holds?(intent_dir, session: session, type: type)
+    FileUtils.touch(path(intent_dir, type: type), mtime: now)
+    true
+  end
+
+  # Owner registers a delegate (D4): a session allowed to write under this
+  # lock. Only the OWNER may delegate; delegates cannot re-delegate.
+  def add_delegate(intent_dir, delegate:, session:, type: "delivery")
+    data = read(intent_dir, type: type)
+    return false if blank?(delegate)
+    return false unless data && data["owner_session"].to_s == session.to_s
+    data["delegates"] = (Array(data["delegates"]) + [delegate.to_s]).uniq
+    write(intent_dir, data, type: type)
+    true
+  end
+
+  # Owner releases the lock (disarm / End tail, D6). force: true is the repair
+  # path's escape hatch for corrupt or own-session rebuilds.
+  # Returns :released, :not_owner, or :none.
+  def release(intent_dir, session:, type: "delivery", force: false)
+    p = path(intent_dir, type: type)
+    return :none unless File.exist?(p)
+    data = read(intent_dir, type: type)
+    unless force || (data && data["owner_session"].to_s == session.to_s)
+      return :not_owner
+    end
+    File.delete(p)
+    :released
+  end
+
+  # Explicit takeover of a stale (or corrupt) lock (D2): replace the lock and
+  # append an audit line to savepoint.md. NEVER takes over a fresh foreign
+  # lock; there is no silent reclaim path anywhere else.
+  # Returns [:taken, data], [:fresh, existing], or acquire's error statuses.
+  def takeover(intent_dir, session:, type: "delivery", host: Socket.gethostname,
+               ttl: TTL_SECONDS, now: Time.now)
+    existing = read(intent_dir, type: type)
+    if existing && !authorized?(existing, session) &&
+       fresh?(intent_dir, type: type, ttl: ttl, now: now)
+      return [:fresh, existing]
+    end
+
+    old_owner = existing ? existing["owner_session"] : "corrupt-or-missing"
+    p = path(intent_dir, type: type)
+    File.delete(p) if File.exist?(p)
+    status, data = acquire(intent_dir, session: session, type: type, host: host,
+                           ttl: ttl, now: now)
+    return [status, data] unless status == :acquired
+
+    audit = "#{now.utc.iso8601}  Lock  takeover: #{session} reclaimed #{type} " \
+            "lock from #{old_owner}\n"
+    File.open(File.join(intent_dir, "savepoint.md"), "a") { |io| io.write(audit) }
+    [:taken, data]
+  end
+
+  # Rewrite the lock file in place (owner-side mutations). A content write also
+  # refreshes the mtime, which is correct: every sanctioned mutation is owner
+  # activity.
+  def write(intent_dir, data, type: "delivery")
+    File.write(path(intent_dir, type: type), JSON.pretty_generate(data))
+  end
+end

package/scripts/lib/power_tools.rb

@@ -4,10 +4,10 @@
 require_relative "qmd_sync"
 
 # PowerTools — detect-then-degrade harness for Plastic's optional power-tools
-# (intent 66b). It owns deterministic detection of each tool and builds an
-# obligation ("mandate") string for whichever tools are present, so the agent is
-# obliged (not merely reminded) to use them: QMD for finding intents, Serena for
-# code navigation.
+# (intent 66b; demoted to recommendations in intent 108, D8). It owns
+# deterministic detection of each tool and builds a RECOMMENDATION string for
+# whichever tools are present, so the agent is reminded (not obliged) to prefer
+# them: QMD for finding intents, Serena for code navigation.
 #
 # Strictly detect-then-degrade: a tool that is absent contributes nothing, and
 # `mandate` returns nil when no tool is present. Nothing here installs anything.
@@ -52,22 +52,21 @@ module PowerTools
     false
   end
 
-  # Obligation text for whichever tools are present, joined by newlines, or nil
-  # when none are. One MANDATORY line per present tool.
+  # Recommendation text for whichever tools are present, joined by newlines, or
+  # nil when none are. One recommendation line per present tool.
   def mandate(cwd:, qmd_detector: QmdSync.method(:detect), serena_detector: nil)
     lines = []
 
     if qmd?(detector: qmd_detector)
-      lines << "MANDATORY: you MUST use QMD (`qmd search` / `qmd query` over the " \
-               "`plastic-*` collections) to check for an existing or related intent " \
-               "before treating this as new work; do not grep/Read the store first."
+      lines << "QMD is available: prefer `qmd search` / `qmd query` over the " \
+               "`plastic-*` collections to check for existing or related intents " \
+               "before treating work as new."
     end
 
     serena_present = serena_detector ? !!serena_detector.call : serena?(cwd: cwd)
     if serena_present
-      lines << "MANDATORY: you MUST use Serena's symbolic tools (find_symbol / " \
-               "get_symbols_overview / find_referencing_symbols) for code navigation " \
-               "before grep/Read."
+      lines << "Serena is available: prefer its symbolic tools (find_symbol / " \
+               "get_symbols_overview / find_referencing_symbols) for code navigation."
     end
 
     return nil if lines.empty?

package/scripts/lib/worktree.rb

@@ -5,6 +5,7 @@ require "json"
 require "yaml"
 require "socket"
 require "time"
+require_relative "lock"
 
 # Worktree -- Plastic-supplied git worktree isolation and the delivery lock
 # (intent 73c / 73c1).
@@ -21,8 +22,8 @@ require "time"
 #   code  worktree  <repo>/.claude/worktrees/{id}--{slug}  branch plastic/{id}--{slug}
 #   store worktree  <plastic_home>/.worktrees/{id}--{slug} branch plastic-store/{id}--{slug}
 #
-# The bridge file doubles as the delivery lock (decision D3): single-owner,
-# stale-lock reclaim via pid liveness.
+# The durable delivery.lock file in the intent dir is the single-owner
+# delivery lock (intent 108): session-keyed, lease-based, explicit takeover.
 #
 # Pure and dependency-injected: every git call goes through an injected
 # `ShellRunner`, so unit tests are hermetic (no real git; inject a fake runner).
@@ -123,6 +124,10 @@ module Worktree
     # into the store commit. Ensure both ignore entries before any worktree add.
     ensure_gitignored(plastic_home, ".worktrees/", runner: runner)
 
+    # The durable lock files live inside intent dirs under the store git repo
+    # (intent 108, D2): transient state, never committed.
+    ensure_gitignored(plastic_home, "*.lock", runner: runner)
+
     # Store worktree: created against the plastic home git repo. Fail-open if the
     # store repo is not a git repo (a fresh global store may be ungit'd).
     store_ok = add_worktree(runner, repo: plastic_home,
@@ -275,46 +280,20 @@ module Worktree
 
   # --- lock ------------------------------------------------------------------
 
-  # pid liveness: signal 0 probes without sending. Any error (no such process,
-  # not ours) means not live.
-  def session_live?(pid)
-    n = Integer(pid) rescue nil
-    return false if n.nil? || n <= 0
-    Process.kill(0, n)
-    true
-  rescue StandardError
-    false
-  end
-
-  # True iff ANOTHER bridge for this intent has a LIVE owner pid that is not
-  # current_session. Scans /tmp/plastic-*.json (or `tmp`). The current session's
-  # own bridge never counts as "other". A dead owner does not hold the lock
-  # (stale-lock reclaim).
-  def lock_held_by_other?(intent_id:, store:, current_session:, home: Dir.home, tmp: nil)
-    tmp ||= default_tmp
-    id = intent_id.to_s
-    st = File.expand_path(store.to_s) unless blank?(store)
-
-    Dir.glob(File.join(tmp, "plastic-*.json")).each do |f|
-      next if f.end_with?(".tmp")
-      data = (JSON.parse(File.read(f)) rescue nil)
-      next unless data.is_a?(Hash)
-
-      intent = data["intent"] || {}
-      next unless intent["id"].to_s == id
-      unless st.nil?
-        bstore = intent["store"].to_s
-        next unless bstore.empty? || File.expand_path(bstore) == st
-      end
-
-      session = data["session"].to_s
-      next if !blank?(current_session) && session == current_session.to_s
-
-      lock = data["lock"] || {}
-      owner_pid = lock["pid"]
-      return true if session_live?(owner_pid)
-    end
-    false
+  # True iff ANOTHER session's delivery.lock is FRESH on this intent's dir
+  # (intent 108, D2): the durable lock file decides; /tmp bridges are not
+  # consulted and no pid is probed. current_session being the owner or a
+  # delegate does not count as "other". A stale lock does not hold (explicit
+  # takeover reclaims it).
+  def lock_held_by_other?(intent_id:, store:, current_session:, home: Dir.home,
+                          ttl: Lock::TTL_SECONDS, now: Time.now)
+    return false if blank?(store)
+    dir = Dir.glob(File.join(File.expand_path(store), "#{intent_id}--*")).first
+    return false unless dir
+    data = Lock.read(dir)
+    return false unless data
+    return false if Lock.authorized?(data, current_session)
+    Lock.fresh?(dir, ttl: ttl, now: now)
   rescue StandardError
     false
   end
@@ -402,8 +381,4 @@ module Worktree
     base[(idx + 2)..]
   end
 
-  def default_tmp
-    t = ENV["PLASTIC_TMP"]
-    (t.nil? || t.strip.empty?) ? "/tmp" : t
-  end
 end

package/scripts/plastic-lock

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+#
+# plastic-lock: inspect and repair the durable delivery lock (intent 108, D5).
+#
+# Usage: plastic-lock <status|fix|release|reclaim|delegate>
+#          [--intent-dir DIR] [--session SID] [--delegate SID]
+#
+# Verbs:
+#   status   report the lock file, the bridge cache, and their agreement
+#   fix      idempotent repair: rebuild lock + bridge from disk truth for the
+#            current session; never touches a fresh foreign lock
+#   release  owner clears the lock (End tail / abandoning a boarding)
+#   reclaim  explicit takeover of a stale lock, audited in savepoint.md
+#   delegate owner registers a subagent session under the lock (D4)
+#
+# Without --intent-dir the intent is resolved from this session's bridge.
+# Exit 0 on success/report; exit 1 when the verb is blocked (held elsewhere).
+
+require "json"
+require_relative "lib/bridge"
+require_relative "lib/lock"
+
+def usage!
+  warn "usage: plastic-lock <status|fix|release|reclaim|delegate> " \
+       "[--intent-dir DIR] [--session SID] [--delegate SID]"
+  exit 1
+end
+
+verb = ARGV.shift
+usage! unless %w[status fix release reclaim delegate].include?(verb)
+
+opts = {}
+until ARGV.empty?
+  case (flag = ARGV.shift)
+  when "--intent-dir" then opts[:dir] = ARGV.shift
+  when "--session" then opts[:session] = ARGV.shift
+  when "--delegate" then opts[:delegate] = ARGV.shift
+  else
+    warn "unknown flag #{flag}"
+    usage!
+  end
+end
+
+session = opts[:session]
+session = ENV["CLAUDE_CODE_SESSION_ID"] if session.nil? || session.strip.empty?
+
+dir = opts[:dir]
+if dir.nil? || dir.strip.empty?
+  bridge = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
+  dir = Bridge.bridge_intent_dir(bridge)
+end
+if dir.nil?
+  warn "plastic-lock: no intent resolved; pass --intent-dir <intent dir>"
+  exit 1
+end
+dir = File.expand_path(dir)
+
+intent_id = Bridge.intent_id_from_dir(dir)
+store = File.dirname(dir)
+name = File.basename(dir)
+key = Bridge.resolve_session(session, intent_id: intent_id, store: store)
+
+case verb
+when "status"
+  lock = Lock.read(dir)
+  bridge = Bridge.read(key)
+  report = {
+    "intent_dir" => dir,
+    "session" => key,
+    "lock" => lock,
+    "lock_fresh" => Lock.fresh?(dir),
+    "lock_corrupt" => Lock.corrupt?(dir),
+    "bridge_present" => !bridge.nil?,
+    "agreement" => (lock && bridge) ?
+      (lock["owner_session"] == bridge.dig("lock", "owner_session")) : nil,
+  }
+  puts JSON.pretty_generate(report)
+when "fix"
+  report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
+                              store: store, name: name)
+  puts JSON.pretty_generate(report)
+  unless report["status"] == "repaired"
+    warn "plastic-lock: #{report['status']} by #{report['owner']}" \
+         "#{report['hint'] ? " (#{report['hint']})" : ''}"
+    exit 1
+  end
+when "release"
+  result = Lock.release(dir, session: key)
+  if result == :not_owner
+    warn "plastic-lock: not the owner; run plastic-lock status"
+    exit 1
+  end
+  data = Bridge.read(key)
+  if data
+    data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
+                     "host" => nil, "type" => nil, "delegates" => [] }
+    Bridge.write(key, data)
+  end
+  puts "released (#{result})"
+when "reclaim"
+  status, lock_data = Lock.takeover(dir, session: key)
+  if status == :fresh
+    warn "plastic-lock: lock is FRESH and held by #{lock_data['owner_session']}; " \
+         "back off (no silent reclaim)"
+    exit 1
+  end
+  report = Bridge.repair_lock(key, intent_id: intent_id, intent_dir: dir,
+                              store: store, name: name)
+  puts JSON.pretty_generate(report)
+when "delegate"
+  usage! if opts[:delegate].nil?
+  ok = Lock.add_delegate(dir, delegate: opts[:delegate], session: key)
+  unless ok
+    warn "plastic-lock: only the lock owner may delegate; run plastic-lock status"
+    exit 1
+  end
+  puts "delegated #{opts[:delegate]} under #{key}"
+end

package/skills/auto/SKILL.md

@@ -56,6 +56,11 @@ It never returns nil, so the gate engages even when every session env var is emp
 never needs a non-empty session env var to function. Arming prints a one-line notice to
 stderr when it falls through to the derived key.
 
+Arming acquires the durable `delivery.lock` in the intent dir, keyed by that resolved
+session. Ownership is session-keyed, not process-keyed, so the arm one-liner exiting
+immediately is fine by construction: the lock stays yours for every later tool call in this
+session. A failed arm raises with a message naming the resolving `plastic-lock` verb.
+
 **Hard rule for the rest of this run:** do NOT edit project code (anything outside the
 intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
 Honor the cycle: What → Why (spec.md) → How (plan.md + actions/ + checklist.md) → Exec.
@@ -84,6 +89,21 @@ Completion report (require-then-synthesize): every dispatched specialist MUST en
 
 Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
 
+### Delegation (subagents writing under the owner's lock)
+
+The enforcer's session owns the delivery lock. Per-stage specialists run in
+their own sessions and would be denied by the lock gate, so register each one
+as a delegate before (or when) it needs to write into the intent dir:
+
+1. Instruct each spawned specialist to report its session id
+   (`CLAUDE_CODE_SESSION_ID`) in its first message.
+2. As the lock owner, run:
+   `ruby ~/.plastic/scripts/plastic-lock delegate --delegate <specialist-session-id>`
+3. If a specialist hits a lock-gate deny, the deny message names this exact
+   command; run it and have the specialist retry.
+
+Only the owner can delegate. Delegates cannot re-delegate or release.
+
 Headless manual gate: when running headless or in the background, still enforce gates manually rather than relying on hooks alone. The PostToolUse gate hook reads `session_id` from hook stdin, and the savepoint ledger write is decoupled from the bridge (derived from the file path, so it fires even with no session id) - these do NOT no-op. What can degrade is the bridge-keyed stage enforcement: if no session id reaches the bridge and no matching bridge is discovered, the stage-gate enforcement step exits without acting, so verify state yourself. The bridge still resolves arming via `CLAUDE_CODE_SESSION_ID` or the derived-key fallback (see the arm-gate note above).
 
 Solo fallback: if the harness has no subagent dispatch, fall back to a single agent walking the full What, Why, How, Exec cycle yourself. This preserves current behavior.
@@ -189,7 +209,10 @@ During initial project creation, all decisions are non-destructive by definition
 ## Completion
 
 1. Verify all checklist items are checked
-2. Write `outcome.md` with detailed results
+2. Write `outcome.md` with detailed results, from `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md`.
+   Set the frontmatter `disposition: delivered` (this is the delivered terminal). `outcome.md`
+   is mandatory at every terminal and self-declares its disposition (see the canonical done-marker
+   and End tail in PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
 3. Write `## Outcome` summary in the intent file (1-2 sentences)
 4. **Release (if configured)**
    1. Detect project — match CWD against paths in `~/.plastic/projects.yml` to find the project slug. If no match, skip to step 5 (default commit-only behavior).
@@ -216,19 +239,15 @@ During initial project creation, all decisions are non-destructive by definition
    ```
    (Use `"abandoned"` instead when the intent is being moved to `## Abandoned`.) Idempotent.
 7. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: deliver intent <ID> — <name>"`
-8. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent).
-   It runs in the background so it never blocks the turn:
-   ```bash
-   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
-   ```
-   Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is the
-   store that holds this intent (the global store or the project store).
-9. Disarm the lifecycle gate (auto delivery is finished):
+8. Disarm the lifecycle gate (auto delivery is finished):
    ```bash
    ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_CODE_SESSION_ID"])'
    ```
-   Disarming also purges stale bridge files from the temp directory automatically (it keeps the
-   current bridge and any live run), so no manual `/tmp` cleanup is needed.
+   Disarm runs the ordered End tail: it releases the worktrees first, then clears the
+   intent's `delivery.lock` (and the bridge's lock cache), and only then is the bridge
+   purge-eligible. Disarming also purges stale bridge files from the temp directory
+   automatically (it keeps the current bridge, any live run, and any bridge whose intent
+   still holds a delivery lock), so no manual `/tmp` cleanup is needed.
 
    **Worktree cleanup (mandatory, intent 73c3).** Disarming performs the worktree release:
    `disarm_auto` calls `Worktree.release`, which removes both per-intent worktrees (the code
@@ -243,6 +262,16 @@ During initial project creation, all decisions are non-destructive by definition
    removed, so the integrated work is not lost. It does this with `Worktree.finish(bridge_data,
    merge: true)` (merge-then-remove). Never leave an orphaned worktree, and run `git worktree
    prune` if you hit a stale reference.
+9. QMD reindex LAST (canonical End tail). AFTER disarm has released the worktrees, cleared the
+   `delivery.lock`, and purged the bridge, refresh the QMD search index for this store (no-op when
+   QMD is absent). It runs in the background so it never blocks the turn:
+   ```bash
+   ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async
+   ```
+   Completion is the lifecycle event that keeps the search index fresh. `<store-root>` is the store
+   that holds this intent (the global store or the project store). The reindex is the LAST End-tail
+   step, run after purge, so the index never references a bridge or lock that is about to disappear
+   (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
 10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling