@zalom/plastic 1.3.0 → 1.4.1

package/scripts/install.rb

@@ -40,10 +40,26 @@ class Install < InstallerCore
     puts "\n\u{1f9e0} Plastic v#{version}\n\n"
 
     if installed? && !reinstall
-      warn "Plastic v#{installed_version} is already installed."
-      warn "  - To upgrade:        npx @zalom/plastic update"
-      warn "  - To re-sync files:  npx @zalom/plastic install --reinstall"
-      return 1
+      # `installed?` is a GLOBAL check (is Plastic core installed for ANY
+      # harness), so it cannot by itself decide whether to refuse: once any
+      # agent is present, a machine that has NEVER installed a second harness
+      # (e.g. Codex, with no ~/.agents, no ~/.codex/hooks.json) must still be
+      # able to add it. Refuse only when EVERY selected agent already has its
+      # own registration (intent 198, D7); otherwise proceed with just the
+      # unregistered ones, and report the already-registered ones without
+      # silently re-syncing them (that is what --reinstall is for).
+      new_agents = selected.reject { |key| agent_installed?(key) }
+      if new_agents.empty?
+        warn "Plastic v#{installed_version} is already installed."
+        warn "  - To upgrade:        npx @zalom/plastic update"
+        warn "  - To re-sync files:  npx @zalom/plastic install --reinstall"
+        return 1
+      end
+
+      already_registered = selected - new_agents
+      run(selected: new_agents, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv,
+          already_registered: already_registered)
+      return 0
     end
 
     run(selected: selected, force: force, reinstall: reinstall, ledger_action: ledger_action, argv: argv)
@@ -51,7 +67,11 @@ class Install < InstallerCore
   end
 
   # Hermetic entrypoint (no prompting / no exit). Returns the per-agent results array.
-  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin)
+  # `already_registered` names agents the gate above found already registered:
+  # they are reported, never re-installed, so the summary line and the Codex
+  # trust reminder only ever count agents that actually changed this run.
+  def run(selected:, force: false, reinstall: false, ledger_action: nil, argv: ARGV, input: $stdin,
+          already_registered: [])
     fresh = !installed?
     mode = fresh ? :install : :update # :update here means "re-sync, skip bootstrap"
 
@@ -60,6 +80,7 @@ class Install < InstallerCore
     apply_config_flags(argv)
 
     results = selected.map { |key| install_for_agent(key, force, argv: argv, input: input, reinstall: reinstall) }
+    results += already_registered.map { |key| already_registered_result(key) }
 
     action = ledger_action || (fresh ? "install" : "reinstall")
     ledger_append(version, action)
@@ -114,10 +135,17 @@ class Install < InstallerCore
     argv[i + 1]
   end
 
+  def already_registered_result(key)
+    config = agent_config(key)
+    { agent: config[:name], success: false, already_registered: true }
+  end
+
   def print_results(results, mode)
     puts "\n\u{2014} Results \u{2014}\n\n"
     results.each do |r|
-      if r[:success]
+      if r[:already_registered]
+        puts "  \u{2139}  #{r[:agent]}: already registered, not re-synced (use --reinstall to re-sync)"
+      elsif r[:success]
         puts "  \u{2705} #{r[:agent]}: #{r[:files]} files installed"
       else
         puts "  \u{26a0}\u{fe0f}  #{r[:agent]}: #{r[:reason]}"
@@ -132,6 +160,23 @@ class Install < InstallerCore
     puts "   Registered for: #{installed.map { |r| r[:agent] }.join(", ")}"
     puts "   Run /clear (or restart your agent) to pick up new conventions."
     puts "   Next: read docs/guides/your-first-intent-in-10-minutes.md\n\n"
+
+    print_codex_hook_trust_reminder(installed)
+  end
+
+  # Codex hooks are installed but INERT until a human reviews and trusts each
+  # hook definition via /hooks (intent 198, Decision D2); Codex keys trust to
+  # the hook's current command hash, so a future release that changes a hook
+  # command re-arms the review. Printed only when a harness that declares its
+  # own home_dir (Codex today) actually installed successfully in this run.
+  # Data-driven from `agents`, never a hardcoded harness name, mirroring the
+  # same reasoning as the D1 presence-probe fix.
+  def print_codex_hook_trust_reminder(installed)
+    codex_like = agents.select { |a| a.key?(:home_dir) }
+    return if codex_like.none? { |a| installed.any? { |r| r[:agent] == a[:name] } }
+
+    puts "   Codex: open Codex, run /hooks, and trust the Plastic hook definitions."
+    puts "   Plastic's gates will not fire until you do.\n\n"
   end
 
   def show_help

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
 
@@ -259,6 +275,34 @@ module Bridge
     auto_pool.max_by { |c| c[:mtime] }&.fetch(:data)
   end
 
+  # --- Shared INDEX entry matcher (intent 188, D12/D13) -----------------------
+  #
+  # ONE definition site for the "- [ID <sep> Title](link)" shape both
+  # `intent_active?` (below) and `scripts/end-intent`'s own INDEX-move parser
+  # depend on, so the two regexes can never drift apart again (the em-dash-only
+  # bug was flagged and deferred at intents 96 and 169, then independently
+  # rediscovered as a SEPARATE end-intent defect at intent 188). Accepts a real
+  # em dash (U+2014) OR a plain hyphen as the id/title separator on READ.
+  # Hardening this widens intent_active?'s fail-open case: a hyphen-formatted
+  # `## Active` line used to read as not-active (lock gate failed open); it now
+  # reads as active (gate correctly blocks). Accepted as a bug fix (D13): no
+  # passing test relied on the old fail-open behavior. Every WRITE still emits
+  # the real em dash (D10); only what this matcher can PARSE has widened.
+  #
+  # The separator is built from the codepoint, not a literal byte in this
+  # source file, so this new code stays em-dash free (the shipped-file
+  # convention; store files like INDEX.md are the exempt surface this matcher
+  # READS, not where this constant lives). Matches the existing convention in
+  # scripts/end-intent.
+  EM_DASH = "\u2014".freeze
+  INDEX_ENTRY_RE = /\A- \[(\S+)\s+(?:#{Regexp.escape(EM_DASH)}|-)\s+(.*?)\]\(([^)]+)\)/.freeze
+
+  # Match `line` (already chomped) against the shared INDEX entry shape.
+  # Returns a MatchData (captures: 1 = id, 2 = title, 3 = link) or nil.
+  def self.index_entry_match(line)
+    line.to_s.match(INDEX_ENTRY_RE)
+  end
+
   # --- Terminal-state bridge purge (intent 80) -------------------------------
 
   # True iff the intent is Active in its store's INDEX.md. An INDEX.md lives at
@@ -284,7 +328,7 @@ module Bridge
       end
       next unless in_active
       break if stripped.start_with?("## ") # next section ends the Active block
-      m = stripped.match(/^- \[(\S+) +—/)
+      m = index_entry_match(stripped)
       return true if m && m[1] == target
     end
     false
@@ -844,7 +888,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}"
@@ -855,24 +900,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
@@ -892,15 +942,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
@@ -964,10 +1018,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))
@@ -982,21 +1046,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
@@ -1110,7 +1184,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)
@@ -1138,20 +1213,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/config_asks.rb

@@ -0,0 +1,110 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+
+# Shared resolution for config_asks.yml: a shipped, declarative manifest that
+# lets a release announce a brand new config question without editing
+# update.rb, doctor.rb, or any skill. Sibling of deprecations.yml (announce
+# only); this one also tracks whether the user has answered or dismissed each
+# entry, via config_asks_dismissed (mirrors deprecations_dismissed).
+#
+# Footgun for whoever adds the next entry: pending reads config.yml directly
+# and never merges in read-config's DEFAULTS, so keying a new entry on
+# something that already has a non-nil value in read-config's DEFAULTS would
+# make that entry look unset, and therefore pending, forever, even though the
+# rest of Plastic already treats it as answered by that default. See the
+# matching note in config_asks.yml's schema header.
+module ConfigAsks
+  FILENAME = "config_asks.yml"
+
+  # nil if the manifest is absent (a legitimate no-op: no release has declared
+  # a config question yet) or valid. A short description of the problem if the
+  # file exists but could not be read or parsed, or does not declare a
+  # config_asks array. Callers use this to tell "nothing declared" apart from
+  # "declared but broken" -- the manifest being unreadable must never look
+  # like a clean pass.
+  def self.manifest_error(plastic_home)
+    path = File.join(plastic_home, FILENAME)
+    return nil unless File.exist?(path)
+
+    data = YAML.safe_load(File.read(path))
+    return "#{FILENAME} does not declare a config_asks list" unless data.is_a?(Hash) && data["config_asks"].is_a?(Array)
+
+    nil
+  rescue StandardError => e
+    "#{FILENAME} could not be read: #{e.message}"
+  end
+
+  # All declared entries, or [] if the manifest is missing or malformed. Use
+  # manifest_error alongside this when the difference between "no entries"
+  # and "could not read the manifest" matters (it always does for a health
+  # check or an announcement -- see manifest_error above).
+  def self.load_entries(plastic_home)
+    path = File.join(plastic_home, FILENAME)
+    return [] unless File.exist?(path)
+
+    data = YAML.safe_load(File.read(path)) || {}
+    entries = data["config_asks"]
+    entries.is_a?(Array) ? entries : []
+  rescue StandardError
+    []
+  end
+
+  # Entries whose key is unset in config.yml AND whose id is not dismissed AND
+  # whose agents (if any) include agent_key. Deliberately ignores "introduced"
+  # -- see the schema comment in config_asks.yml for why (retro-fire).
+  #
+  # agent_key: nil means "do not filter by agent" (every entry applies); pass
+  # the caller's actual agent ("claude", "codex", "hermes") to respect an
+  # entry's agents scoping.
+  def self.pending(plastic_home, agent_key = nil)
+    config = load_config(plastic_home)
+    dismissed = Array(config["config_asks_dismissed"])
+
+    load_entries(plastic_home).select do |entry|
+      next false if dismissed.include?(entry["id"])
+      next false unless applies_to_agent?(entry, agent_key)
+
+      value = dig(config, entry["key"].to_s)
+      value.nil? || value == ""
+    end
+  end
+
+  # The exact command that answers one option of one entry.
+  def self.write_config_command(plastic_home, key, value)
+    "ruby #{File.join(plastic_home, "scripts", "write-config")} #{key} #{value}"
+  end
+
+  # The exact command that dismisses one entry ("not now" / keep default).
+  def self.dismiss_command(plastic_home, id)
+    "ruby #{File.join(plastic_home, "scripts", "write-config")} config_asks_dismissed --push #{id}"
+  end
+
+  # An entry with no agents field (or an empty one) applies to every agent.
+  # Otherwise it applies only when agent_key is nil (no filtering requested)
+  # or is present in the entry's agents list.
+  def self.applies_to_agent?(entry, agent_key)
+    scoped = Array(entry["agents"])
+    return true if scoped.empty?
+    return true if agent_key.nil?
+
+    scoped.include?(agent_key)
+  end
+  private_class_method :applies_to_agent?
+
+  def self.load_config(plastic_home)
+    path = File.join(plastic_home, "config.yml")
+    return {} unless File.exist?(path)
+
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+  private_class_method :load_config
+
+  def self.dig(hash, dotted_key)
+    dotted_key.split(".").reduce(hash) { |acc, k| acc.is_a?(Hash) ? acc[k] : nil }
+  end
+  private_class_method :dig
+end

package/scripts/lib/graph_rebuild.rb

@@ -197,11 +197,17 @@ module GraphRebuild
 
   # Classify a resolved (store, id) relative to the referer, using the live store
   # index to detect dead targets:
-  #   - target id present in the referer's OWN store -> :same_store (collapse to bare)
-  #   - target id present in a DIFFERENT store       -> :cross_store (keep slug:id)
-  #   - target id present NOWHERE                     -> :dead (drop)
+  #   - the store token resolves to no known store          -> :unknown_store (NEVER
+  #     dropped; this is what makes a future discovery miss non-destructive, intent 189 D2)
+  #   - target id present in the referer's OWN known store   -> :same_store (collapse)
+  #   - target id present in a DIFFERENT known store          -> :cross_store (keep slug:id)
+  #   - target id present NOWHERE in a known store            -> :dead (drop)
   def classify(store_tok, bare, referer_store, store_index, original_ref)
     canonical = canonical_store_key(store_tok, store_index)
+    unless known_store?(canonical, store_index)
+      return { status: :unknown_store, ref: original_ref.to_s, store: store_tok }
+    end
+
     if ids_in(store_index, canonical).include?(bare)
       if canonical == referer_store
         { status: :same_store, id: bare }
@@ -213,6 +219,15 @@ module GraphRebuild
     end
   end
 
+  # True iff `canonical` names a store this run actually knows about (it is "global", or a
+  # literal key in `store_index`). A ref whose store token canonicalizes to anything else
+  # has never been discovered by this run, and must be classified :unknown_store, never
+  # :dead: those are different facts (store unknown vs. id absent from a known store) and
+  # only the second one means the ref is genuinely gone.
+  def known_store?(canonical, store_index)
+    canonical == "global" || (store_index || {}).key?(canonical)
+  end
+
   def ids_in(store_index, store_key)
     Array((store_index || {})[store_key])
   end
@@ -225,8 +240,11 @@ module GraphRebuild
   #   relocation_map — from build_relocation_map (spans all stores)
   #   store_index    — { store_key => bare ids present } (spans all stores)
   #
-  # Returns { nodes: <new map>, changes: [ {intent:, kind:, before:, after:} ] }.
-  # kinds: :dedupe, :i3, :repoint, :collapse, :drop, :i1_backlink.
+  # Returns { nodes: <new map>, changes: [ {intent:, kind:, before:, after:} ],
+  #           preserved: [ {intent:, field:, ref:, store:} ] }.
+  # kinds (changes, real mutations only): :dedupe, :i3, :repoint, :collapse, :drop,
+  # :i1_backlink. `preserved` is DIFFERENT: an unknown-store ref left byte-for-byte
+  # unchanged, reported for visibility, never counted as a "change" (nothing mutated).
   #
   # Order is load-bearing (spec Phase 2):
   #   1. dedupe each array order-preserving
@@ -247,6 +265,7 @@ module GraphRebuild
     end
 
     changes = []
+    preserved = []
 
     out.each do |id, edges|
       # 1. dedupe order-preserving
@@ -289,6 +308,11 @@ module GraphRebuild
               changes << { intent: id, kind: :repoint, field: field, before: ref, after: res[:ref] }
             end
             rebuilt << res[:ref]
+          when :unknown_store
+            # NEVER drop: the store is unrecognized, not the id absent from a known store.
+            # Preserve byte-for-byte and report separately from `changes` (nothing mutated).
+            preserved << { intent: id, field: field, ref: ref, store: res[:store] }
+            rebuilt << ref
           when :dead
             changes << { intent: id, kind: :drop, field: field, before: ref, after: nil }
             # dropped: not appended
@@ -323,6 +347,6 @@ module GraphRebuild
       end
     end
 
-    { nodes: out, changes: changes }
+    { nodes: out, changes: changes, preserved: preserved }
   end
 end

package/scripts/lib/hook_registry.rb

@@ -48,6 +48,7 @@ module HookRegistry
         ] },
         { "matcher" => "Write|Edit", "hooks" => [
           { "name" => "savepoint-pre", "status" => "Recording stage start..." },
+          { "name" => "links-gate", "status" => "Checking Links gate..." },
         ] },
         { "matcher" => CREATE_MATCHER, "hooks" => [
           { "name" => "create-gate", "status" => "Checking create gate..." },
@@ -84,9 +85,29 @@ module HookRegistry
   # [{"matcher","hooks":[{"type":"command","command","statusMessage"}]}]}},
   # identical to Claude's shape, string command. Single source of truth (108 D7):
   # any drift from `events` is a bug, pinned by test.
-  CODEX_PRE_HOOKS  = %w[code-gate lock-gate savepoint-pre create-gate].freeze
+  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.
@@ -100,11 +121,21 @@ 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
 
   # The settings.json shape merge_claude_hooks expects: single-group events map