@zalom/plastic 1.0.0-beta.23 → 1.0.0-beta.25

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.
@@ -227,8 +247,11 @@ During initial project creation, all decisions are non-destructive by definition
    ```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

package/skills/doctor/SKILL.md

@@ -119,9 +119,12 @@ Use the `fix_hint` value to determine the correct action:
 | "Inject the missing required frontmatter field(s)" | Edit the intent's `{ID}--{slug}.md` frontmatter to add the missing key (e.g. `chain: []`) without touching other keys |
 | "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (or invoke the `plastic-add-project-store` skill) to create the missing store |
 | "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
+| "Dispatch plastic-intent-curator ... revisions.md ..." | Invoke the `plastic-intent-curator` (or the agent) to relocate the flagged section or ref into the intent's `revisions.md` via move-and-record (one dated, `[rule: <tag>]`-tagged entry per item), per PLASTIC.md > Structural maintenance and revisions.md. For a missing required section, restore or reproject it instead. |
 
 For fixes the agent cannot handle automatically, explain what the user needs
-to do manually.
+to do manually. The `revisions.md` remedy is curator-applied (a move-and-record
+relocation, not a mechanical edit) and stays human-gated by the Step 4
+Fix / Select / Skip prompt.
 
 ### Step 6: Verify
 

package/skills/intent-starting/SKILL.md

@@ -34,7 +34,14 @@ enforces it: without a held lock, mutating writes to this active intent's dir ar
 1. **Ensure the intent is in INDEX `## Active`.** If it sits in `## Future`, activate it
    (move it to `## Active`, auto-commit) before arming. Creation precedes activation, so a
    brand-new What intent is activated here, then locked.
-2. **Arm the bridge.** Which arm is chosen by the mode answer (below), but the lock itself is
+2. **Self-heal the lock state first.** Run:
+   `ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <STORE>/<dir>`
+   This is the one repair function (same one /plastic-lock exposes): it removes
+   corrupt or legacy lock state and rebuilds the lock and bridge from disk for
+   this session. If it reports `held`, another session owns the intent: STOP
+   and tell the user who holds it. If it reports `stale`, ask the user before
+   running `plastic-lock reclaim` (takeover is audited).
+3. **Arm the bridge.** Which arm is chosen by the mode answer (below), but the lock itself is
    taken first. Reuse the arm one-liner shape from `plastic-auto`:
    ```bash
    # guided (lock only):
@@ -55,8 +62,14 @@ deterministic derived key (a hash of the store and intent id). It never returns
 lock is taken even when every session env var is empty; arming prints a one-line stderr
 notice when it falls through to the derived key.
 
-Idempotent re-arm: arming again with the same owner just refreshes the lock (re-derives and
-rewrites the bridge); it is not an error to re-board an intent this session already owns.
+**What the lock IS.** Ownership is session-keyed and lease-based: arming writes a durable
+`delivery.lock` file in the intent dir naming this session as owner, and the owner's hooks
+refresh the file mtime on tool activity (the lease heartbeat). The /tmp bridge is only a
+cache of that file; on any disagreement the lock file wins, so a wiped /tmp never strands
+the owner. Idempotent re-arm: arming again with the same owner just refreshes the lock; it
+is not an error to re-board an intent this session already owns. A failed arm raises with
+a message naming the resolving `plastic-lock` verb (`status`, `reclaim`, or `fix`): follow
+that message, never delete a lock file by hand.
 
 ## Confirm delivery state
 

package/skills/lock/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: lock
+description: Inspect, repair, release, or reclaim an intent's delivery lock. Use when a lock-gate deny names /plastic-lock, when resuming interrupted work after a crash, reboot, or /tmp wipe, when a lock reads held or stale, or when the user says "fix the lock", "who holds the lock", or "reclaim the lock".
+---
+
+# Plastic Lock
+
+Command-only wrapper around `~/.plastic/scripts/plastic-lock`. The durable
+delivery lock is a `delivery.lock` file in the intent directory: ownership is
+session-keyed, liveness is a lease (the owner's hooks refresh the file mtime;
+stale means the heartbeat is older than the TTL). The /tmp bridge is only a
+cache; the lock file wins every disagreement.
+
+## Verbs
+
+Run from the project (the intent resolves from this session's bridge), or pass
+`--intent-dir` explicitly:
+
+| Verb | What it does | When |
+|---|---|---|
+| `status` | Report the lock file, bridge cache, freshness, agreement | Always safe; run first |
+| `fix` | Idempotent repair: rebuild lock + bridge from disk truth for THIS session. Never touches a fresh foreign lock | Interrupted work, corrupted state, /tmp wiped, legacy pid locks |
+| `release` | Owner clears the lock | Ending or abandoning a boarding |
+| `reclaim` | Explicit takeover of a STALE lock; appends an audit line to savepoint.md | The owner is gone and the lease expired |
+| `delegate` | Owner registers a subagent session under the lock (`--delegate <session-id>`) | Auto-mode orchestration |
+
+```
+ruby ~/.plastic/scripts/plastic-lock status
+ruby ~/.plastic/scripts/plastic-lock fix --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock reclaim --intent-dir <store>/<id>--<slug>
+ruby ~/.plastic/scripts/plastic-lock delegate --delegate <subagent-session-id>
+```
+
+## Rules
+
+- `fix` exits non-zero when another session holds a FRESH lock: back off, do
+  not retry in a loop. `status` shows the owner.
+- `reclaim` refuses a fresh lock. There is no silent reclaim anywhere; every
+  takeover is audited in the intent's savepoint.md.
+- Acquiring a lock for new work is NOT this skill's job: board through
+  `/plastic-intent-starting`, which calls the same repair internally.