@zalom/plastic 1.4.0 → 1.5.0

package/scripts/lib/bridge.rb

@@ -21,6 +21,16 @@ module Bridge
   # (<id>--<slug>.md) is never sentineled; it is born complete.
   PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
 
+  # Single place a skill-reference string gets built (intent 201, D3): every
+  # message that used to write "/plastic-something" by hand calls this
+  # instead, so a fourth harness only teaches ITS prefix once instead of
+  # hunting the codebase for hardcoded slashes. The actual prefix table lives
+  # on Lock (see lock.rb), which bridge.rb already requires; this is a thin
+  # delegator so every call site in this file reads Bridge.skill_ref.
+  def self.skill_ref(name, harness: :claude)
+    Lock.skill_ref(name, harness: harness)
+  end
+
   # Bridge cleanup is terminal-state, not age-based (intent 80). A bridge is dead
   # weight ONLY once its intent is terminal (no longer in its store's INDEX.md
   # `## Active` block); such bridges are purged. An Active intent's bridge is kept
@@ -87,6 +97,12 @@ module Bridge
       "host" => lock_data["host"],
       "type" => lock_data["type"],
       "delegates" => Array(lock_data["delegates"]),
+      "owner_harness" => lock_data["owner_harness"],
+      "owner_agent" => lock_data["owner_agent"],
+      "owner_model" => lock_data["owner_model"],
+      "owner_thread" => lock_data["owner_thread"],
+      "run_mode" => lock_data["run_mode"],
+      "delegate_activity" => Array(lock_data["delegate_activity"]),
     }
   end
 
@@ -782,13 +798,12 @@ module Bridge
         "warning_at" => 80,
         "critical_at" => 90
       },
-      # Worktree isolation block (intent 73c). Born unprovisioned; arm_auto calls
-      # Worktree.provision to fill it. code/store are abs paths or null.
+      # Worktree isolation block (intent 73c; store-worktree half retired by
+      # intent 178). Born unprovisioned; arm_auto calls Worktree.provision to
+      # fill it. "code" is an abs path or null.
       "worktree" => {
         "code" => nil,
         "code_branch" => nil,
-        "store" => nil,
-        "store_branch" => nil,
         "provisioned" => false
       },
       # Delivery-lock CACHE block (intent 108, D2). The durable truth is the
@@ -872,7 +887,8 @@ module Bridge
   # and arm_guided (auto: false) are thin delegators so the lock-stamp + provision
   # behaviour stays identical across both modes. Works even when no bridge exists
   # yet (mid-session intent creation).
-  def self.arm(session, intent_id:, intent_dir:, store:, name:, auto:)
+  def self.arm(session, intent_id:, intent_dir:, store:, name:, auto:, harness: nil,
+               agent: nil, model: nil, thread: nil)
     key = resolve_session(session, intent_id: intent_id, store: store)
     if blank?(session) && blank?(ENV["CLAUDE_CODE_SESSION_ID"])
       $stderr.puts "plastic: no session id available; arming with derived bridge key #{key}"
@@ -883,24 +899,29 @@ module Bridge
     # Acquire the durable delivery lock (D1/D2): session-keyed, O_EXCL, in the
     # intent dir. The bridge lock block is a cache of the file.
     intent_dir_abs = File.expand_path(intent_dir)
-    status, lock_data = Lock.acquire(intent_dir_abs, session: key)
+    status, lock_data = Lock.acquire(intent_dir_abs, session: key,
+                                     harness: harness, agent: agent,
+                                     model: model, thread: thread,
+                                     run_mode: auto ? "auto" : "guided")
     case status
     when :acquired, :owned
       data["lock"] = lock_cache(lock_data)
     when :held
       raise LockHeldError, "delivery lock for intent #{intent_id} is held by " \
-        "session #{lock_data && lock_data['owner_session']}; run /plastic-doctor " \
-        "check the lock status"
+        "session #{lock_data && lock_data['owner_session']}; run " \
+        "#{skill_ref('plastic-doctor', harness: harness)} check the lock status"
     when :stale
       raise LockHeldError, "delivery lock for intent #{intent_id} is stale " \
-        "(owner #{lock_data && lock_data['owner_session']}); run /plastic-doctor " \
-        "reclaim the lock to take it over with an audit"
+        "(owner #{lock_data && lock_data['owner_session']}); run " \
+        "#{skill_ref('plastic-doctor', harness: harness)} reclaim the lock to take it " \
+        "over with an audit"
     when :excluded
       raise LockHeldError, "a #{lock_data && lock_data['type']} lock is active on " \
-        "intent #{intent_id}; run /plastic-doctor check the lock status"
+        "intent #{intent_id}; run #{skill_ref('plastic-doctor', harness: harness)} check " \
+        "the lock status"
     when :corrupt
       raise LockHeldError, "delivery.lock for intent #{intent_id} is unreadable; " \
-        "run /plastic-doctor fix the lock"
+        "run #{skill_ref('plastic-doctor', harness: harness)} fix the lock"
     end
 
     # Provision the per-intent worktrees (mandatory code worktree for project
@@ -920,15 +941,19 @@ module Bridge
 
   # Arm auto mode for a session+intent. Works even when no bridge exists yet
   # (mid-session intent creation). Re-derives intent state, then sets build.auto.
-  def self.arm_auto(session, intent_id:, intent_dir:, store:, name:)
-    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name, auto: true)
+  def self.arm_auto(session, intent_id:, intent_dir:, store:, name:, harness: nil,
+                    agent: nil, model: nil, thread: nil)
+    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name,
+        auto: true, harness: harness, agent: agent, model: model, thread: thread)
   end
 
   # Acquire the delivery lock WITHOUT auto mode (intent 96 / Start guided branch).
   # Mirrors arm_auto's lock-stamp + worktree provision but leaves build.auto = false.
   # Same signature as arm_auto; disarm_auto (mode-agnostic) releases a guided lock.
-  def self.arm_guided(session, intent_id:, intent_dir:, store:, name:)
-    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name, auto: false)
+  def self.arm_guided(session, intent_id:, intent_dir:, store:, name:, harness: nil,
+                      agent: nil, model: nil, thread: nil)
+    arm(session, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name,
+        auto: false, harness: harness, agent: agent, model: model, thread: thread)
   end
 
   # Degrade path for disarm_auto when no intent_id is given (intent 131): the
@@ -992,10 +1017,20 @@ module Bridge
   # reclaim verb (Lock.takeover). Two entry points call this: the
   # plastic-lock CLI and /plastic-intent-starting (self-healing boarding).
   def self.repair_lock(session, intent_id:, intent_dir:, store:, name:,
-                       now: Time.now, tmp: tmp_dir)
+                       now: Time.now, tmp: tmp_dir, harness: nil,
+                       agent: nil, model: nil, thread: nil, run_mode: nil,
+                       hint_harness: nil)
     key = resolve_session(session, intent_id: intent_id, store: store)
     dir = File.expand_path(intent_dir)
     actions = []
+    previous = read(key, intent_id: intent_id, tmp: tmp)
+    auto = !!(previous && previous.dig("build", "auto"))
+    derived_mode = if previous && previous.dig("build").is_a?(Hash) &&
+                      previous["build"].key?("auto")
+                     auto ? "auto" : "guided"
+                   end
+    identity = { harness: harness, agent: agent, model: model, thread: thread,
+                 run_mode: blank?(run_mode) ? derived_mode : run_mode.to_s }
 
     if Lock.corrupt?(dir)
       File.delete(Lock.path(dir))
@@ -1010,21 +1045,31 @@ module Bridge
       end
       return { "status" => "stale", "owner" => lock["owner_session"],
                "actions" => actions, "session" => key,
-               "hint" => "run /plastic-doctor reclaim the lock to take over with an audit" }
+               "hint" => "run #{skill_ref('plastic-doctor', harness: hint_harness || harness)} reclaim the " \
+                         "lock to take over with an audit" }
     end
 
     if lock
-      Lock.heartbeat(dir, session: key, now: now)
-      lock_data = Lock.read(dir)
+      if lock["owner_session"].to_s == key.to_s
+        lock_data = lock.dup
+        { "owner_harness" => harness, "owner_agent" => agent,
+          "owner_model" => model, "owner_thread" => thread,
+          "run_mode" => identity[:run_mode] }.each do |field, value|
+          lock_data[field] = value.to_s unless blank?(value)
+        end
+        Lock.write(dir, lock_data)
+        Lock.heartbeat(dir, session: key, now: now)
+      else
+        Lock.heartbeat(dir, session: key, now: now)
+        lock_data = Lock.read(dir)
+      end
       role = lock_data["owner_session"].to_s == key ? "owner" : "delegate"
       actions << "lock kept (#{role})"
     else
-      status, lock_data = Lock.acquire(dir, session: key, now: now)
+      status, lock_data = Lock.acquire(dir, session: key, now: now, **identity)
       actions << "lock #{status}"
     end
 
-    previous = read(key, intent_id: intent_id, tmp: tmp)
-    auto = !!(previous && previous.dig("build", "auto"))
     data = derive(key, intent_id: intent_id, intent_dir: dir, store: store,
                   name: name, tmp: tmp)
     data["build"]["auto"] = auto
@@ -1138,7 +1183,8 @@ module Bridge
   # target's lock names as owner or delegate (even when stale: a stale lock is
   # still its owner's until an explicit takeover).
   def self.lock_gate_decision(bridge_data, file_path, session: nil,
-                              ttl: Lock::TTL_SECONDS, now: Time.now, home: Dir.home)
+                              ttl: Lock::TTL_SECONDS, now: Time.now, home: Dir.home,
+                              harness: :claude)
     return nil if blank?(file_path)
 
     target_dir = intent_dir_for(file_path)
@@ -1166,20 +1212,23 @@ module Bridge
                "#{lock['owner_session']}. Back off; if you are the owner's " \
                "subagent, the owner must run: plastic-lock delegate " \
                "--intent-dir #{target_dir} --session <your-session-id>. " \
-               "Inspect with /plastic-doctor check the lock status"
+               "Inspect with #{skill_ref('plastic-doctor', harness: harness)} check the " \
+               "lock status"
       end
       return solo_allow(id, "stale delivery lock") if solo
       return "intent #{id} has a stale delivery lock (owner " \
-             "#{lock['owner_session']}); run /plastic-doctor reclaim the lock to " \
-             "take it over, or /plastic-doctor fix the lock"
+             "#{lock['owner_session']}); run #{skill_ref('plastic-doctor', harness: harness)} " \
+             "reclaim the lock to take it over, or " \
+             "#{skill_ref('plastic-doctor', harness: harness)} fix the lock"
     end
     if Lock.corrupt?(target_dir)
       return solo_allow(id, "unreadable delivery.lock") if solo
-      return "delivery.lock for intent #{id} is unreadable; run /plastic-doctor fix the lock"
+      return "delivery.lock for intent #{id} is unreadable; run " \
+             "#{skill_ref('plastic-doctor', harness: harness)} fix the lock"
     end
     return solo_allow(id, "no delivery lock") if solo
-    "no delivery lock held for intent #{id}; run /plastic-intent-starting " \
-      "to lock and begin"
+    "no delivery lock held for intent #{id}; run " \
+      "#{skill_ref('plastic-intent-starting', harness: harness)} to lock and begin"
   end
 
   # A session holds an intent's lock iff the durable delivery.lock in the

package/scripts/lib/hook_registry.rb

@@ -88,6 +88,26 @@ module HookRegistry
   CODEX_PRE_HOOKS  = %w[code-gate lock-gate savepoint-pre links-gate create-gate].freeze
   CODEX_POST_HOOKS = %w[gate-check].freeze
 
+  # Codex's shell-tool gate hole (intent 203): bash-gate (denies a shell write to
+  # project code before How) and retrieval-gate (advisory, never denies) both
+  # belong on the Bash matcher, and ONLY Bash: the official Codex hooks doc's
+  # PreToolUse event catalog enumerates exactly Bash, apply_patch, and MCP tool
+  # calls, and neither it nor the two prior Codex research passes (198's
+  # official-docs research, 181's deep research) documents a discrete Read,
+  # Grep, or Glob tool name (D3). So this does NOT copy Claude's four-name
+  # "Bash|Read|Grep|Glob" retrieval-gate matcher; registering a tool name Codex
+  # never reports would be dead weight that looks alive, the exact defect this
+  # intent exists to fix.
+  CODEX_BASH_HOOKS = %w[bash-gate retrieval-gate].freeze
+
+  # Live-state events registered WHOLE (intent 199), unlike CODEX_PRE_HOOKS/
+  # CODEX_POST_HOOKS above: Codex's SessionStart/UserPromptSubmit/PreCompact already
+  # match Claude's shape exactly, one matcher group each ("", no tool to collapse
+  # onto), so every hook `events` lists under these three events projects straight
+  # through with no allowlist to keep in sync. A hook added to any of them on the
+  # Claude side registers for Codex automatically.
+  CODEX_LIVE_STATE_EVENTS = %w[SessionStart UserPromptSubmit PreCompact].freeze
+
   def codex_hooks_json(dispatcher_path:)
     # name => statusMessage, straight from the single `events` source (A8): the
     # guide Part 3 hooks.json format carries a per-hook statusMessage, so emit it.
@@ -101,11 +121,33 @@ module HookRegistry
     # Preserve the order these hook names appear across the PreToolUse groups in `events`.
     pre_order = events["PreToolUse"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
     pre = (pre_order & CODEX_PRE_HOOKS).map { |n| cmd.call(n) }
+    bash = (pre_order & CODEX_BASH_HOOKS).map { |n| cmd.call(n) }
     post = CODEX_POST_HOOKS.map { |n| cmd.call(n) }
-    {
-      "PreToolUse"  => [{ "matcher" => "apply_patch", "hooks" => pre }],
+
+    result = {
+      "PreToolUse"  => [
+        { "matcher" => "apply_patch", "hooks" => pre },
+        { "matcher" => "Bash", "hooks" => bash },
+      ],
       "PostToolUse" => [{ "matcher" => "apply_patch", "hooks" => post }],
     }
+    CODEX_LIVE_STATE_EVENTS.each do |event|
+      names = events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+      result[event] = [{ "matcher" => "", "hooks" => names.map { |n| cmd.call(n) } }]
+    end
+    result
+  end
+
+  # Flattened, deduplicated Claude launcher names for every hook `events`
+  # registers (intent 204): each hook name maps to a hooks/<name> launcher
+  # installed as ~/.claude/hooks/plastic-<name>. The single derivation doctor's
+  # hooks_exist/hooks_executable/hooks_no_orphans checks read from, so a
+  # hand-kept list of launchers can never drift out of step with `events`
+  # again (the gap that let 8 of 15 launchers, all the enforcement gates, go
+  # unchecked).
+  def claude_launcher_names
+    events.values.flatten.flat_map { |g| g["hooks"].map { |h| h["name"] } }
+          .uniq.sort.map { |name| "plastic-#{name}" }
   end
 
   # The settings.json shape merge_claude_hooks expects: single-group events map

package/scripts/lib/installer_core.rb

@@ -17,9 +17,10 @@ class InstallerCore
   DEFAULT_PLASTIC_HOME = File.join(Dir.home, ".plastic")
 
   DEFAULT_AGENTS = [
-    { key: "claude", name: "Claude Code", dir: File.join(Dir.home, ".claude"), flag: "--claude" },
+    { key: "claude", name: "Claude Code", dir: File.join(Dir.home, ".claude"), flag: "--claude",
+      skill_prefix: "/" },
     { key: "codex", name: "Codex CLI", dir: File.join(Dir.home, ".agents"),
-      home_dir: File.join(Dir.home, ".codex"), flag: "--codex" },
+      home_dir: File.join(Dir.home, ".codex"), flag: "--codex", skill_prefix: "$" },
     { key: "hermes", name: "Hermes", dir: File.join(Dir.home, ".hermes"), flag: "--hermes" },
   ].freeze
 
@@ -43,7 +44,8 @@ class InstallerCore
     - The full conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly.
       It is generated and overwritten on Plastic updates, so never edit it.
     - Operational procedures are installed as skills under ~/.agents/skills/ (each
-      plastic-<name>/SKILL.md). Use them for the lifecycle work they describe.
+      plastic-<name>/SKILL.md). Invoke one explicitly as $plastic-<name> (for example
+      $plastic-doctor), or let Codex pick one implicitly by matching its description.
     - Intents, specs, plans, checklists, and outcomes live under ~/.plastic/, never in
       the project tree.
 
@@ -175,7 +177,7 @@ class InstallerCore
     return ["claude"] unless input.tty?
 
     puts "Which agents should Plastic register for?\n\n"
-    agents.each_with_index { |a, i| puts "  #{i + 1}. #{a[:name]} (#{a[:dir]})" }
+    agents.each_with_index { |a, i| puts "  #{i + 1}. #{a[:name]} (#{a[:home_dir] || a[:dir]})" }
     puts "  #{agents.size + 1}. All"
     puts
 
@@ -328,6 +330,11 @@ class InstallerCore
       "scripts/rebuild-graph" => "scripts/rebuild-graph",
       "scripts/lib/restore_intent_v1.rb" => "scripts/lib/restore_intent_v1.rb",
       "scripts/restore-intent-v1" => "scripts/restore-intent-v1",
+"scripts/lib/revisions_writer.rb" => "scripts/lib/revisions_writer.rb",
+"scripts/maintenance-run" => "scripts/maintenance-run",
+"scripts/lib/maintenance_git.rb" => "scripts/lib/maintenance_git.rb",
+"scripts/lib/worktree_sweep.rb" => "scripts/lib/worktree_sweep.rb",
+"scripts/sweep-store-worktrees" => "scripts/sweep-store-worktrees",
       "scripts/validate-intent" => "scripts/validate-intent",
       "scripts/new-intent" => "scripts/new-intent",
       "scripts/end-intent" => "scripts/end-intent",
@@ -420,12 +427,44 @@ class InstallerCore
     (data["files"] || {}).keys
   end
 
+  # Per-agent registration probe (intent 198, D7 follow-up). `installed?` in
+  # install.rb only answers "is Plastic core installed at all", which cannot
+  # tell two harnesses apart: once core is present, install.rb's old gate
+  # refused to add ANY new harness, even one that had never been touched. This
+  # asks the narrower, correct question, "has Plastic already registered
+  # files for THIS agent", using the signal already tracked for prune-on-update:
+  # the per-agent manifest (manifest_path_for). A missing manifest file, or a
+  # manifest whose "files" list is empty (write_manifest still writes one when
+  # nothing was installed), both mean nothing is registered for this agent yet.
+  # An unknown key is never "installed" (fail toward proceeding, since a caller
+  # that already validated the key gets its own "Unknown agent" result from
+  # install_for_agent).
+  def agent_installed?(key)
+    config = agent_config(key)
+    return false unless config
+    !manifest_files(manifest_path_for(key, config)).empty?
+  end
+
   def install_for_agent(key, force, argv: [], input: $stdin, reinstall: false)
     config = agent_config(key)
     return { agent: config[:name], success: false, reason: "Unknown agent" } unless config
 
-    unless File.directory?(config[:dir])
-      return { agent: config[:name], success: false, reason: "#{config[:dir]} not found \u{2014} #{config[:name]} not installed?" }
+    # Presence probe (intent 198, Decision D1): an agent that declares its own
+    # home directory (Codex, home_dir: ~/.codex) is checked THERE, because
+    # config[:dir] (~/.agents) is the shared cross-tool skills root, not
+    # anything Codex itself creates. A fresh Codex install has no ~/.agents
+    # yet, so testing config[:dir] aborted a genuinely-present Codex. Claude
+    # and Hermes declare no home_dir, so presence_dir resolves to config[:dir]
+    # exactly as before and their behavior is unchanged. The failure message
+    # reuses the same resolved directory, so it always names the directory
+    # actually tested. install_codex still needs config[:dir] to exist by the
+    # time it writes skills; install_skills_flat and generate_codex_agents
+    # already FileUtils.mkdir_p their own nested paths under config[:dir] and
+    # config[:home_dir], so a fresh install creates it as a side effect (no
+    # separate top-level mkdir_p is required here).
+    presence_dir = config[:home_dir] || config[:dir]
+    unless File.directory?(presence_dir)
+      return { agent: config[:name], success: false, reason: "#{presence_dir} not found, #{config[:name]} not installed?" }
     end
 
     # Capture the prior manifest so we can prune files that no longer ship

package/scripts/lib/lock.rb

@@ -24,7 +24,30 @@ require "time"
 module Lock
   module_function
 
+  # Skill-invocation prefix per harness (intent 201, D2/D3). Claude Code invokes a
+  # skill with a slash (/plastic-doctor); Codex CLI invokes explicitly with a
+  # dollar ($plastic-doctor) and may also select one implicitly by matching the
+  # skill's description. This table is the actual source of truth for
+  # Bridge.skill_ref (bridge.rb requires lock.rb, never the reverse, so the
+  # table lives here rather than pulling Bridge into this dependency-free file
+  # just to render two characters). InstallerCore::DEFAULT_AGENTS carries the
+  # same values per adapter as documented config (see ACTION_2); this constant
+  # is not read from it at runtime, by the same reasoning bridge.rb/hook-*
+  # already stay clear of installer_core.rb (spec Alternatives Considered).
+  SKILL_PREFIXES = { "claude" => "/", "codex" => "$" }.freeze
+
+  # Renders a skill reference for the given harness. Unset or unrecognized
+  # harness falls back to Claude's slash form, so an existing call site that
+  # never passes harness: keeps behaving exactly as it does today (D2). name
+  # is the bare skill name ("plastic-doctor"), never pre-prefixed.
+  def self.skill_ref(name, harness: :claude)
+    prefix = SKILL_PREFIXES.fetch(harness.to_s, SKILL_PREFIXES["claude"])
+    "#{prefix}#{name}"
+  end
+
   TYPES = %w[delivery maintenance].freeze
+  DELEGATE_ACTIVITY_LIMIT = 20
+  DELEGATE_STATUSES = %w[active finished failed].freeze
 
   # Lease TTL. Heartbeats fire from the write-path hooks (PostToolUse
   # gate-check and the lock-gate allow path), so a delivering session
@@ -84,7 +107,8 @@ module Lock
   #   [: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)
+              ttl: TTL_SECONDS, now: Time.now, harness: nil, agent: nil,
+              model: nil, thread: nil, run_mode: nil)
     raise ArgumentError, "unknown lock type #{type.inspect}" unless TYPES.include?(type)
     raise ArgumentError, "lock session must be present" if blank?(session)
 
@@ -99,7 +123,13 @@ module Lock
     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"]))
+                       delegates: Array(existing["delegates"]),
+                       delegate_activity: Array(existing["delegate_activity"]),
+                       harness: merged_value(harness, existing["owner_harness"]),
+                       agent: merged_value(agent, existing["owner_agent"]),
+                       model: merged_value(model, existing["owner_model"]),
+                       thread: merged_value(thread, existing["owner_thread"]),
+                       run_mode: merged_value(run_mode, existing["run_mode"]))
         write(intent_dir, data, type: type)
         return [:owned, data]
       end
@@ -107,7 +137,9 @@ module Lock
       return [:stale, existing]
     end
 
-    data = payload(session: session, type: type, host: host, now: now)
+    data = payload(session: session, type: type, host: host, now: now,
+                   harness: harness, agent: agent, model: model, thread: thread,
+                   run_mode: run_mode)
     File.open(path(intent_dir, type: type),
               File::WRONLY | File::CREAT | File::EXCL) do |io|
       io.write(JSON.pretty_generate(data))
@@ -117,16 +149,49 @@ module Lock
     [:held, read(intent_dir, type: type)] # lost the O_EXCL race
   end
 
-  def payload(session:, type:, host:, now:, delegates: [])
+  def payload(session:, type:, host:, now:, delegates: [], delegate_activity: [],
+              harness: nil, agent: nil, model: nil, thread: nil, run_mode: nil)
     {
       "type" => type,
       "owner_session" => session.to_s,
       "host" => host,
       "acquired_at" => now.utc.iso8601,
       "delegates" => delegates,
+      "owner_harness" => normalized_value(harness),
+      "owner_agent" => normalized_value(agent),
+      "owner_model" => normalized_value(model),
+      "owner_thread" => normalized_value(thread),
+      "run_mode" => normalized_value(run_mode),
+      "delegate_activity" => bounded_delegate_activity(delegate_activity, delegates: delegates),
     }
   end
 
+  def normalized_value(value)
+    blank?(value) ? nil : value.to_s
+  end
+
+  def merged_value(explicit, existing)
+    blank?(explicit) ? normalized_value(existing) : explicit.to_s
+  end
+
+  # Keep every active record that still names an authorized delegate, while
+  # bounding completed history. Active work is current truth and must never be
+  # evicted merely because newer delegates finished.
+  def bounded_delegate_activity(records, delegates:)
+    records = Array(records)
+    authorized = Array(delegates).map(&:to_s)
+    terminal_indexes = records.each_index.reject do |index|
+      record = records[index]
+      record.is_a?(Hash) && record["status"].to_s == "active" &&
+        authorized.include?(record["session"].to_s)
+    end.last(DELEGATE_ACTIVITY_LIMIT)
+    records.each_with_index.filter_map do |record, index|
+      active = record.is_a?(Hash) && record["status"].to_s == "active" &&
+               authorized.include?(record["session"].to_s)
+      record if active || terminal_indexes.include?(index)
+    end
+  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)
@@ -136,11 +201,49 @@ module Lock
 
   # 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")
+  def add_delegate(intent_dir, delegate:, session:, type: "delivery", now: Time.now,
+                   harness: nil, agent: nil, model: nil, thread: nil)
     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
+    activity = Array(data["delegate_activity"])
+    previous = activity.find { |record| record.is_a?(Hash) && record["session"].to_s == delegate.to_s }
+    activity.reject! { |record| record.is_a?(Hash) && record["session"].to_s == delegate.to_s }
+    record = {
+      "session" => delegate.to_s,
+      "status" => "active",
+      "registered_at" => now.utc.iso8601,
+      "last_activity_at" => now.utc.iso8601,
+      "harness" => merged_value(harness, previous && previous["harness"]),
+      "agent" => merged_value(agent, previous && previous["agent"]),
+      "model" => merged_value(model, previous && previous["model"]),
+      "thread" => merged_value(thread, previous && previous["thread"]),
+    }
+    data["delegate_activity"] = bounded_delegate_activity(activity + [record],
+                                                          delegates: data["delegates"])
+    write(intent_dir, data, type: type)
+    true
+  end
+
+  # Activity metadata is observational only. Finishing or failing a delegate
+  # never removes its string session id from the authorization list.
+  def update_delegate_status(intent_dir, delegate:, status:, session:, type: "delivery",
+                             now: Time.now)
+    return false unless (DELEGATE_STATUSES - ["active"]).include?(status.to_s)
+    data = read(intent_dir, type: type)
+    return false unless data && data["owner_session"].to_s == session.to_s
+    activity = Array(data["delegate_activity"])
+    index = activity.index do |record|
+      record.is_a?(Hash) && record["session"].to_s == delegate.to_s
+    end
+    return false unless index
+    activity[index] = activity[index].merge(
+      "status" => status.to_s,
+      "last_activity_at" => now.utc.iso8601
+    )
+    data["delegate_activity"] = bounded_delegate_activity(activity,
+                                                          delegates: data["delegates"])
     write(intent_dir, data, type: type)
     true
   end
@@ -164,7 +267,8 @@ module Lock
   # 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)
+               ttl: TTL_SECONDS, now: Time.now, harness: nil, agent: nil,
+               model: nil, thread: nil, run_mode: nil)
     existing = read(intent_dir, type: type)
     if existing && !authorized?(existing, session) &&
        fresh?(intent_dir, type: type, ttl: ttl, now: now)
@@ -175,7 +279,8 @@ module Lock
     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)
+                           ttl: ttl, now: now, harness: harness, agent: agent,
+                           model: model, thread: thread, run_mode: run_mode)
     return [status, data] unless status == :acquired
 
     audit = "#{now.utc.iso8601}  Lock  takeover: #{session} reclaimed #{type} " \
@@ -190,6 +295,75 @@ module Lock
   def write(intent_dir, data, type: "delivery")
     File.write(path(intent_dir, type: type), JSON.pretty_generate(data))
   end
+
+  # Read-only normalized inspection. The lock file and its mtime remain the
+  # sole sources of owner and heartbeat truth; no environment or transcript
+  # inference belongs here.
+  def who(intent_dir, ttl: TTL_SECONDS, now: Time.now)
+    p = path(intent_dir)
+    unless File.exist?(p)
+      return { "state" => "none",
+               "claims" => Claim.claims_status(intent_dir, ttl: ttl, now: now) }
+    end
+    data = read(intent_dir)
+    unless data
+      return { "state" => "corrupt",
+               "claims" => Claim.claims_status(intent_dir, ttl: ttl, now: now) }
+    end
+
+    activity = Array(data["delegate_activity"])
+    activity_by_session = activity.each_with_object({}) do |record, memo|
+      memo[record["session"].to_s] = record if record.is_a?(Hash)
+    end
+    authorized_sessions = Array(data["delegates"]).map(&:to_s)
+    activity_sessions = activity.filter_map do |record|
+      record["session"].to_s if record.is_a?(Hash) &&
+                                authorized_sessions.include?(record["session"].to_s)
+    end.uniq
+    activity_order = activity.each_with_index.each_with_object({}) do |(record, index), memo|
+      memo[record["session"].to_s] = index if record.is_a?(Hash)
+    end
+    activity_sessions.sort_by! do |session|
+      record = activity_by_session[session] || {}
+      # Active delegates are current ahead of terminal delegates. Within that
+      # group, latest activity wins; original record order is the stable
+      # fallback for legacy records without timestamps.
+      [record["status"].to_s == "active" ? 1 : 0,
+       record["last_activity_at"].to_s, activity_order.fetch(session, -1)]
+    end
+    # Legacy string-only delegates retain their authorization order. Rich
+    # records follow in deterministic current/latest order, so consumers may
+    # reliably take the last projection entry: the most recent active delegate
+    # when one exists, otherwise the most recent terminal activity.
+    ordered_sessions = (authorized_sessions - activity_sessions) + activity_sessions
+    delegates = ordered_sessions.map do |session|
+      record = activity_by_session[session] || {}
+      {
+        "session" => session,
+        "harness" => normalized_value(record["harness"]) || "unknown",
+        "agent" => normalized_value(record["agent"]) || "unknown",
+        "model" => normalized_value(record["model"]) || "unknown",
+        "thread" => normalized_value(record["thread"]) || "unknown",
+        "status" => normalized_value(record["status"]) || "unknown",
+        "registered_at" => record["registered_at"],
+        "last_activity_at" => record["last_activity_at"],
+      }
+    end
+    {
+      "state" => fresh?(intent_dir, ttl: ttl, now: now) ? "fresh" : "stale",
+      "owner" => {
+        "harness" => normalized_value(data["owner_harness"]) || "unknown",
+        "agent" => normalized_value(data["owner_agent"]) || "unknown",
+        "model" => normalized_value(data["owner_model"]) || "unknown",
+        "thread" => normalized_value(data["owner_thread"]) || "unknown",
+        "run_mode" => normalized_value(data["run_mode"]) || "unknown",
+      },
+      "owner_session" => data["owner_session"],
+      "heartbeat_at" => File.mtime(p).utc.iso8601,
+      "delegates" => delegates,
+      "claims" => Claim.claims_status(intent_dir, ttl: ttl, now: now),
+    }
+  end
 end
 
 # Claim: the per-artifact claim-token layer (intent 111, D1/D7). Sits BENEATH
@@ -359,7 +533,8 @@ module Claim
   # ENGAGES only when a claim file exists (dormant otherwise, so single-owner flows
   # and the existing suite stay green, AC7). Fails open on stale/corrupt via
   # fail_open?, the named contract.
-  def claim_gate_reason(intent_dir, artifact, session:, ttl: Lock::TTL_SECONDS, now: Time.now)
+  def claim_gate_reason(intent_dir, artifact, session:, ttl: Lock::TTL_SECONDS, now: Time.now,
+                        harness: :claude)
     return nil if Lock.blank?(artifact)
     return nil unless File.exist?(path(intent_dir, artifact))   # dormant: no claim
     return nil if holds_claim?(intent_dir, artifact, session: session)  # you hold it
@@ -368,8 +543,8 @@ module Claim
     holder = data && data["owner_session"]
     since = data && data["acquired_at"]
     "artifact #{artifact} is claimed by #{holder} since #{since}; another writer holds " \
-      "it. Back off or run /plastic-doctor check the lock status. If you are a distinct " \
-      "delegate, the owner must register you: plastic-lock delegate --intent-dir " \
-      "#{intent_dir} --session <your-session-id>"
+      "it. Back off or run #{Lock.skill_ref('plastic-doctor', harness: harness)} check the " \
+      "lock status. If you are a distinct delegate, the owner must register you: " \
+      "plastic-lock delegate --intent-dir #{intent_dir} --session <your-session-id>"
   end
 end