@zalom/plastic 1.8.0 → 1.10.0

package/scripts/lib/installer_core.rb

@@ -8,6 +8,7 @@ require "digest"
 require "time"
 require_relative "hook_registry"
 require_relative "agent_models"
+require_relative "harness_text"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
@@ -32,17 +33,20 @@ class InstallerCore
   # Regex matching exactly one managed section (BEGIN line .. END line), non-greedy.
   CODEX_SECTION_RE = /^<!-- BEGIN PLASTIC INTEGRATION.*?-->\n.*?\n<!-- END PLASTIC INTEGRATION -->\n?/m
 
-  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md, injected into
-  # ~/.codex/AGENTS.md. Not a slice of PLASTIC.md (which is already over the 32 KiB
-  # AGENTS.md merge cap on its own), so it never drifts and carries no maintenance fork.
+  # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the plastic-conventions
+  # skill, injected into ~/.codex/AGENTS.md. Not a slice of PLASTIC.md itself: AGENTS.md is
+  # a shared file Codex merges from multiple sources, so this block stays a small,
+  # hand-curated pointer rather than embedding the core wholesale, and it never drifts
+  # because it only ever points, never duplicates.
   CODEX_AGENTS_MD_BODY = <<~MD.freeze
     Plastic is installed for this agent. Plastic is intent-driven state management: all
     work flows through an intent, moved through What, Why, How, then Exec. Do not jump
     straight to code.
 
     Standing rules:
-    - 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.
+    - Core conventions live in ~/.plastic/PLASTIC.md. Read it and follow it exactly. For
+      depth, read a chapter from ~/.agents/skills/plastic-conventions/references/ on demand.
+      Both are generated and overwritten on Plastic updates, so never edit them.
     - Operational procedures are installed as skills under ~/.agents/skills/ (each
       plastic-<name>/SKILL.md). Invoke one explicitly as $plastic-<name> (for example
       $plastic-doctor), or let Codex pick one implicitly by matching its description.
@@ -232,9 +236,17 @@ class InstallerCore
   def distribute(mode)
     puts "  \u{1f4e6} #{mode == :update ? "Updating" : "Installing"} core files to #{plastic_home}"
 
+    manifest_path = File.join(plastic_home, "manifest.json")
+    # Capture the prior manifest before the copy loop touches anything, so a
+    # file dropped from core_files (renamed/removed) can be pruned below
+    # instead of orphaning forever. Mirrors install_for_agent's prune (D14
+    # Why-gate correction: this global path never had it).
+    old_files = manifest_files(manifest_path)
+
     FileUtils.mkdir_p(plastic_home)
     FileUtils.mkdir_p(File.join(plastic_home, "scripts", "lib"))
     FileUtils.mkdir_p(File.join(plastic_home, "templates"))
+    FileUtils.mkdir_p(File.join(plastic_home, "hooks"))
 
     core_files.each do |src, dest|
       src_path = File.join(package_root, src)
@@ -248,13 +260,23 @@ class InstallerCore
     File.write(File.join(plastic_home, "VERSION"), "#{version}\n")
 
     Dir.glob(File.join(plastic_home, "scripts", "*")).each { |f| FileUtils.chmod(0o755, f) if File.file?(f) }
+    # Same treatment for the hook launchers, and UNCONDITIONAL on update as well as install:
+    # FileUtils.cp onto an existing file keeps the DESTINATION's old mode, so a copy over a
+    # non-executable predecessor would stay non-executable forever and capture3 would raise
+    # EACCES into the same silent fail-open this intent is closing. *.json is skipped because
+    # hooks.json is a registry, not a program (same reasoning as test/rubyopt_clearing_test.rb).
+    Dir.glob(File.join(plastic_home, "hooks", "*")).each do |f|
+      FileUtils.chmod(0o755, f) if File.file?(f) && !f.end_with?(".json")
+    end
 
     global_files = core_files.values.map { |d| File.join(plastic_home, d) }
     global_files << File.join(plastic_home, "VERSION")
     global_files = global_files.select { |p| File.exist?(p) }
-    write_manifest(global_files, File.join(plastic_home, "manifest.json"))
+    write_manifest(global_files, manifest_path)
+
+    pruned = prune_removed_files(old_files - global_files, root: plastic_home)
 
-    puts "  \u{2705} Core files synced (v#{version})"
+    puts "  \u{2705} Core files synced (v#{version})#{pruned.positive? ? ", #{pruned} stale file(s) pruned" : ""}"
   end
 
   # Templates ship in full: every file under templates/ in the repo must reach
@@ -271,18 +293,35 @@ class InstallerCore
     end
   end
 
+  # Hook launchers ship in full: scripts/codex-hook resolves a live-state launcher at
+  # __dir__/../hooks/<gate>, which is ~/.plastic/hooks/<gate> once installed, so the launchers
+  # have to BE there or every Codex live-state hook fails open with no message (intent 249).
+  # Glob-derived for the same reason template_files is: a hand-written list hid two template
+  # files from every install for five weeks (intent 190), and a new hook must register itself.
+  # No path rewrite on this copy, unlike install_claude's: the launchers resolve their core
+  # through "$SCRIPT_DIR/../scripts/", which from ~/.plastic/hooks/ already lands on
+  # ~/.plastic/scripts/. Copied whole, hooks.json and run-hook and statusline included: all
+  # three are inert at that path, and an exclusion list is exactly the maintenance this avoids.
+  def hook_files
+    Dir.glob(File.join(package_root, "hooks", "*")).each_with_object({}) do |path, acc|
+      next unless File.file?(path)
+
+      rel = File.join("hooks", File.basename(path))
+      acc[rel] = rel
+    end
+  end
+
   # Files copied into ~/.plastic on install/update. Every verb script + the shared lib
   # must be here so the installed ~/.plastic/scripts copy is self-complete (sync-guarded
   # by install_sync_test). The templates half is glob-derived (template_files above); the
   # rest stays a hand-written literal.
   def core_files
-    hand_registered_files.merge(template_files)
+    hand_registered_files.merge(template_files).merge(hook_files)
   end
 
   def hand_registered_files
     {
       "PLASTIC.md" => "PLASTIC.md",
-      "PLASTIC-reference.md" => "PLASTIC-reference.md",
       "deprecations.yml" => "deprecations.yml",
       "config_asks.yml" => "config_asks.yml",
       "scripts/folgezettel-id" => "scripts/folgezettel-id",
@@ -294,17 +333,16 @@ class InstallerCore
       "scripts/hook-future-intent-check" => "scripts/hook-future-intent-check",
       "scripts/hook-gate-check" => "scripts/hook-gate-check",
       "scripts/hook-savepoint-pre" => "scripts/hook-savepoint-pre",
-      "scripts/hook-qmd-search" => "scripts/hook-qmd-search",
+      "scripts/hook-power-tools" => "scripts/hook-power-tools",
       "scripts/lib/qmd_hook.rb" => "scripts/lib/qmd_hook.rb",
       "scripts/lib/power_tools.rb" => "scripts/lib/power_tools.rb",
+      "scripts/lib/ruby_probe.rb" => "scripts/lib/ruby_probe.rb",
       "scripts/lib/agent_models.rb" => "scripts/lib/agent_models.rb",
       "scripts/lib/config_asks.rb" => "scripts/lib/config_asks.rb",
       "scripts/lib/release_guard.rb" => "scripts/lib/release_guard.rb",
       "scripts/hook-code-gate" => "scripts/hook-code-gate",
       "scripts/hook-lock-gate" => "scripts/hook-lock-gate",
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
-      "scripts/hook-retrieval-gate" => "scripts/hook-retrieval-gate",
-      "scripts/lib/retrieval_gate.rb" => "scripts/lib/retrieval_gate.rb",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
       "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
@@ -345,7 +383,11 @@ class InstallerCore
       "scripts/hook-create-gate" => "scripts/hook-create-gate",
       "scripts/hook-links-gate" => "scripts/hook-links-gate",
       "scripts/lib/links_gate.rb" => "scripts/lib/links_gate.rb",
+      "scripts/lib/edit_gates.rb" => "scripts/lib/edit_gates.rb",
+      "scripts/hook-edit-gates" => "scripts/hook-edit-gates",
       "scripts/lib/apply_patch_envelope.rb" => "scripts/lib/apply_patch_envelope.rb",
+      "scripts/lib/codex_edit_gates.rb" => "scripts/lib/codex_edit_gates.rb",
+      "scripts/lib/harness_text.rb" => "scripts/lib/harness_text.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
@@ -359,7 +401,17 @@ class InstallerCore
       "scripts/uninstall.rb" => "scripts/uninstall.rb",
       "scripts/rollback.rb" => "scripts/rollback.rb",
       "scripts/lib/outcome_guard.rb" => "scripts/lib/outcome_guard.rb",
+      "scripts/lib/spec_header.rb" => "scripts/lib/spec_header.rb",
+      "scripts/lib/scaffold_intent.rb" => "scripts/lib/scaffold_intent.rb",
+      "scripts/scaffold-intent" => "scripts/scaffold-intent",
+      "scripts/lib/verify_intent.rb" => "scripts/lib/verify_intent.rb",
+      "scripts/verify-intent" => "scripts/verify-intent",
+      "scripts/lib/start_intent.rb" => "scripts/lib/start_intent.rb",
+      "scripts/start-intent" => "scripts/start-intent",
+      "scripts/lib/exec_worktree.rb" => "scripts/lib/exec_worktree.rb",
+      "scripts/exec-worktree" => "scripts/exec-worktree",
       "scripts/doctor.rb" => "scripts/doctor.rb",
+      "scripts/lib/doctor_core.rb" => "scripts/lib/doctor_core.rb",
       "scripts/dashboard.rb" => "scripts/dashboard.rb",
       "scripts/skill-lint" => "scripts/skill-lint",
       "scripts/lib/skill_lint.rb" => "scripts/lib/skill_lint.rb",
@@ -403,10 +455,11 @@ class InstallerCore
     MD
 
     write_if_missing(File.join(plastic_home, "AGENTS.md"), <<~MD)
-      # Plastic \u{2014} Agent Instructions
+      # Plastic: Agent Instructions
 
-      Read `PLASTIC.md` in this directory. It contains all Plastic conventions.
-      Follow it exactly. Never modify it \u{2014} it is overwritten on plugin updates.
+      Read `PLASTIC.md` in this directory for the core conventions; deeper doctrine lives
+      in the `plastic-conventions` skill's chapters. Follow it exactly. Never modify it:
+      it is overwritten on plugin updates.
 
       This file (`AGENTS.md`) is where project-specific rules live.
 
@@ -508,7 +561,8 @@ class InstallerCore
              end
 
     new_files = manifest_files(manifest_path_for(key, config))
-    pruned = prune_removed_files(old_files - new_files)
+    pruned = prune_removed_files(old_files - new_files,
+                                  root: [config[:dir], config[:home_dir], *shared_fragment_prune_roots])
     result[:pruned] = pruned if pruned.positive?
 
     # The legacy manifest is fully superseded once the new one is written; delete it so
@@ -588,7 +642,8 @@ class InstallerCore
         restore_agent(config)
         result = { agent: config[:name], success: false, reason: "verify failed - restored prior snapshot" }
       else
-        prune_removed_files(manifest_files(manifest_path_for(key, config)))
+        prune_removed_files(manifest_files(manifest_path_for(key, config)),
+                             root: [config[:dir], config[:home_dir], *shared_fragment_prune_roots])
         result = { agent: config[:name], success: false, reason: "verify failed - partial install pruned" }
       end
     end
@@ -599,10 +654,30 @@ class InstallerCore
 
   # Delete tracked files present in the old manifest but absent from the new one,
   # then remove any now-empty skill directories they lived in.
-  def prune_removed_files(stale_files)
+  #
+  # `root:` is a mandatory containment boundary (intent 223 F5): every manifest path
+  # is read back from JSON written by write_manifest and could, on a hand-edited or
+  # otherwise corrupt manifest, name a path outside the install this call is pruning
+  # (for example `distribute` prunes against `~/.plastic/`, `install_for_agent` prunes
+  # against one agent's own directories). Accepts a single path or an array (an agent
+  # with a two-root schema, like Codex's `dir` plus `home_dir`, tracks files under
+  # both, so a single boundary would wrongly reject legitimate prunes under the root
+  # not passed). A candidate that resolves outside every given root is skipped and
+  # never deleted, so a stray manifest entry can never delete a path outside the
+  # target home.
+  def prune_removed_files(stale_files, root:)
+    expanded_roots = Array(root).compact.map { |r| File.expand_path(r) }
     removed = 0
     dirs = []
     stale_files.each do |f|
+      if path_contained?(f, store_roots)
+        warn "  \u{26a0}\u{fe0f}  Refused to prune #{f}: inside the intent store"
+        next
+      end
+      unless path_contained?(f, expanded_roots)
+        warn "  \u{26a0}\u{fe0f}  Skipped prune of #{f}: outside #{expanded_roots.join(", ")}"
+        next
+      end
       if File.exist?(f)
         File.delete(f)
         removed += 1
@@ -615,6 +690,54 @@ class InstallerCore
     removed
   end
 
+  # True when `path`, once expanded, is one of `roots` itself or lives underneath
+  # one of them. String-prefix containment guarded by a trailing separator so a
+  # sibling directory that merely shares a prefix (`/home/x-evil` vs root `/home/x`)
+  # never counts as contained.
+  def path_contained?(path, roots)
+    expanded = File.expand_path(path)
+    Array(roots).any? { |root| expanded == root || expanded.start_with?(root + File::SEPARATOR) }
+  end
+
+  # Intent 223 (post-delivery hardening): the user's entire intent history lives under
+  # `plastic_home/store` (the global store) and `plastic_home/projects` (every project
+  # store). `distribute` legitimately prunes with `root: plastic_home`, which CONTAINS
+  # both directories, so the ordinary `root:` containment check in `prune_removed_files`
+  # admits a store path instead of refusing it. Today that branch is unreachable (the
+  # pruned set is always `old_files - global_files`, both derived from `core_files` plus
+  # `VERSION`, so no store path can ever appear there), so this is defense in depth for
+  # an unreachable case, not a fix for a live bug. It exists because the standing rule is
+  # that NO path ever deletes the global or project intent stores, and the cost of being
+  # wrong (irreversible loss of the user's whole intent history) warrants a guard that
+  # fails milder than the bug it prevents, independent of what any caller's `root:` is or
+  # what a hand-edited manifest claims.
+  def store_roots
+    [File.join(plastic_home, "store"), File.join(plastic_home, "projects")].map { |p| File.expand_path(p) }
+  end
+
+  # `install_skills_flat` relocates any top-level underscore-prefixed markdown
+  # fragment (today: `_active-intent-gate.md`, `_decision-tables.md`) out of the
+  # per-agent skills tree and into `plastic_home` directly, then lists them in
+  # `installed`, so they are manifest-tracked and eligible for prune. But
+  # `install_for_agent`'s prune roots are `[config[:dir], config[:home_dir]]`,
+  # which do not cover `plastic_home`, so those two files could never actually be
+  # pruned (every attempt printed "Skipped prune of ... outside ..." to stderr).
+  #
+  # Fix scope (intent 223 N3): add each shared fragment's exact FILE path as its
+  # own containment root, never `plastic_home` itself as a directory root.
+  # `path_contained?` only matches a candidate that equals a root exactly or
+  # lives under `root + separator`; a root that is itself a file path can never
+  # have children, so listing these exact files as roots permits pruning ONLY
+  # those files, never anything else under `plastic_home`. This keeps
+  # `~/.plastic/store` and `~/.plastic/projects` (the user's intent stores, never
+  # prunable by standing rule) outside every prune root.
+  def shared_fragment_prune_roots
+    skills_source = File.join(package_root, "skills")
+    return [] unless File.directory?(skills_source)
+    Dir.children(skills_source).select { |e| e.start_with?("_") && e.end_with?(".md") }
+       .map { |e| File.join(plastic_home, e) }
+  end
+
   def install_claude(config, force, argv: [], input: $stdin, reinstall: false)
     hooks_dir = File.join(config[:dir], "hooks")
     skills_root = File.join(config[:dir], "skills")
@@ -678,7 +801,16 @@ class InstallerCore
     installed = []
     skills_source = File.join(package_root, "skills")
     skill_exclude = advisor_enabled? ? [] : ["agent-advisor"]
-    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"), exclude: skill_exclude) if File.directory?(skills_source)
+    # Intent 239: Codex is the one harness that gets its instruction text projected at
+    # copy time. skill_names comes from the real skills/ listing, so the rewrite table
+    # maintains itself as skills are added and renamed. Every OTHER install path passes
+    # no transform and keeps the byte-for-byte copy.
+    skill_names = Dir.children(skills_source).select { |e| File.directory?(File.join(skills_source, e)) }
+    codex_transform = lambda do |content, rel|
+      HarnessText.for_codex(content, rel_path: rel, skill_names: skill_names)
+    end
+    installed += install_skills_flat(skills_source, File.join(config[:dir], "skills"),
+                                     exclude: skill_exclude, transform: codex_transform) if File.directory?(skills_source)
     # Codex-scoped overrides only (agents.models.codex.*): a literal Claude
     # model id set under agents.models.claude.* (or the legacy flat form,
     # which resolves as claude) must never reach a Codex TOML.
@@ -870,15 +1002,19 @@ class InstallerCore
   # instead, so every skill can read it from one shared location. `exclude` skips
   # named top-level skill directories entirely (intent 185: the agent-advisor skill
   # when advisor.enabled is false).
-  def install_skills_flat(skills_source, skills_root, exclude: [])
+  def install_skills_flat(skills_source, skills_root, exclude: [], transform: nil)
     installed = []
     FileUtils.mkdir_p(skills_root)
 
     Dir.children(skills_source).reject { |e| e.start_with?(".") || exclude.include?(e) }.each do |entry|
       src = File.join(skills_source, entry)
       if File.directory?(src)
-        installed += copy_dir_recursive(src, File.join(skills_root, "plastic-#{entry}"))
+        installed += copy_dir_recursive(src, File.join(skills_root, "plastic-#{entry}"),
+                                        transform: transform, rel_prefix: entry)
       elsif entry.start_with?("_") && entry.end_with?(".md")
+        # Spec D8: shared fragments land in the HARNESS-NEUTRAL plastic_home, shared
+        # with any co-installed Claude. Never transformed, or a Codex install would
+        # corrupt Claude's copy of the same file.
         FileUtils.mkdir_p(plastic_home)
         dest = File.join(plastic_home, entry)
         FileUtils.cp(src, dest)
@@ -1377,16 +1513,22 @@ class InstallerCore
     agents.find { |a| a[:key] == key }
   end
 
-  def copy_dir_recursive(src, dest)
+  def copy_dir_recursive(src, dest, transform: nil, rel_prefix: "")
     files = []
     FileUtils.mkdir_p(dest)
     Dir.entries(src).reject { |e| e.start_with?(".") }.each do |entry|
       src_path = File.join(src, entry)
       dest_path = File.join(dest, entry)
+      rel = rel_prefix.empty? ? entry : File.join(rel_prefix, entry)
       if File.directory?(src_path)
-        files += copy_dir_recursive(src_path, dest_path)
+        files += copy_dir_recursive(src_path, dest_path, transform: transform, rel_prefix: rel)
       elsif File.file?(src_path)
-        FileUtils.cp(src_path, dest_path)
+        if transform && File.extname(entry) == ".md"
+          File.write(dest_path, transform.call(File.read(src_path), rel))
+          File.chmod(File.stat(src_path).mode & 0o7777, dest_path)
+        else
+          FileUtils.cp(src_path, dest_path)
+        end
         files << dest_path
       end
     end

package/scripts/lib/lock.rb

@@ -56,6 +56,37 @@ module Lock
   # either way (takeover), so the TTL only bounds WHEN takeover is allowed.
   TTL_SECONDS = 1800
 
+  # The write guard is a mutex, not a lock in the Plastic sense: it carries no
+  # owner, no timestamp, and no content, it is only an inode to flock. It is
+  # a SIBLING of delivery.lock (never delivery.lock itself), because renaming
+  # over a file you hold an flock on leaves you holding an orphaned inode
+  # while the next writer flocks a fresh one at the same path. The name lands
+  # inside the existing *.lock rule in ~/.plastic/.gitignore, so no gitignore
+  # change is needed.
+  WRITE_GUARD_TIMEOUT_SECONDS = 2.0
+  WRITE_GUARD_RETRY_SECONDS = 0.01
+
+  # The sibling guard path for a lock type. NOT built by passing a compound
+  # type: into path (see TYPES comment above): Lock.path(dir, type:
+  # "delivery.write") would render the same string, and the exclusion at
+  # acquire ((TYPES - [type]).first) silently checks only one other type, so
+  # a third TYPES entry would break mutual exclusion with no error. This
+  # helper keeps the guard entirely outside TYPES.
+  def write_guard_path(intent_dir, type: "delivery")
+    File.join(intent_dir, "#{type}.write.lock")
+  end
+
+  # The sibling temp path for write's write-to-temp-then-rename. Ends in
+  # ".lock" (not just ".tmp") so a temp orphaned by a crash between the
+  # write and the rename is covered by the store's existing *.lock
+  # .gitignore rule rather than committed by the store's `git add -A`
+  # auto-commit. Sibling in the same directory as the target, never a
+  # system tmpdir, because File.rename can raise EXDEV across filesystems.
+  def write_temp_path(intent_dir, type: "delivery")
+    "#{path(intent_dir, type: type)}.tmp.#{Process.pid}.#{Thread.current.object_id}." \
+      "#{Time.now.to_f}.lock"
+  end
+
   def blank?(value)
     value.nil? || value.to_s.strip.empty?
   end
@@ -122,15 +153,30 @@ module Lock
     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"]),
-                       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)
+        # Re-read happens INSIDE the guard so the read-modify-write is
+        # covered, not just the write (spec D5). Fall back to the
+        # already-read existing when the file has vanished underneath us.
+        # If the re-read shows a different owner, keep today's outcome and
+        # write anyway: an owner-changed-underneath refusal would be new
+        # semantics the spec does not authorize. The rebuilt payload then
+        # carries THIS session as owner while inheriting the NEW owner's
+        # delegate list, merging two lock identities into one record. The
+        # window is a takeover landing between the pre-guard read and the
+        # guarded re-read; no test covers it, and closing it means guarding
+        # takeover itself, which this intent's scope does not authorize.
+        data = with_write_guard(intent_dir, type: type) do
+          record = read(intent_dir, type: type) || existing
+          rebuilt = payload(session: session, type: type, host: host, now: now,
+                            delegates: Array(record["delegates"]),
+                            delegate_activity: Array(record["delegate_activity"]),
+                            harness: merged_value(harness, record["owner_harness"]),
+                            agent: merged_value(agent, record["owner_agent"]),
+                            model: merged_value(model, record["owner_model"]),
+                            thread: merged_value(thread, record["owner_thread"]),
+                            run_mode: merged_value(run_mode, record["run_mode"]))
+          write(intent_dir, rebuilt, type: type)
+          rebuilt
+        end
         return [:owned, data]
       end
       return [:held, existing] if fresh?(intent_dir, type: type, ttl: ttl, now: now)
@@ -203,27 +249,32 @@ module Lock
   # lock. Only the OWNER may delegate; delegates cannot re-delegate.
   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
+    # The read moves inside the guard (spec D5): a guard around the write
+    # alone still loses updates, since both writers already read the stale
+    # copy before contending for the guard.
+    with_write_guard(intent_dir, type: type) do
+      data = read(intent_dir, type: type)
+      next 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
   end
 
   # Activity metadata is observational only. Finishing or failing a delegate
@@ -231,21 +282,23 @@ module Lock
   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
+    with_write_guard(intent_dir, type: type) do
+      data = read(intent_dir, type: type)
+      next 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
+      next 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
-    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
 
   # Owner releases the lock (disarm / End tail, D6). force: true is the repair
@@ -289,11 +342,107 @@ module Lock
     [: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.
+  # Bounded mutual exclusion for the read-modify-write callers of write (spec
+  # D3, D5): acquire's re-acquire branch, add_delegate, and
+  # update_delegate_status each read, modify, then write, and the guard must
+  # span the whole sequence, not just the write, or two writers that already
+  # read the stale copy before contending still lose an update.
+  #
+  # NOT re-entrant: it opens a fresh file descriptor on every call, and flock
+  # is scoped to the open file description, so a nested acquisition from the
+  # same process would conflict with its own outer hold and burn the whole
+  # timeout budget on every single write. write must never take this guard
+  # itself; only the three read-modify-write call sites do.
+  #
+  # Fails open on every edge, per Plastic's fail-open doctrine (intent 93 D7,
+  # 111, 112): when the guard file cannot be opened, and when the flock
+  # cannot be won inside guard_timeout, the block still runs and its value is
+  # still returned. The write still happens, still atomically; the worst case
+  # on timeout is exactly today's possibly-lost update, never a torn file and
+  # never a hang.
+  #
+  # The guard file must never be deleted, by anyone, ever. Unlinking an
+  # flock target is the unlink-recreate race: a later opener would create a
+  # fresh inode and stop serializing against the current holder, breaking
+  # mutual exclusion exactly when contention is highest. scripts/write-config:59
+  # leaves config.yml.lock in place for the same reason. A leftover guard
+  # file is inert: nothing reads it, it stays zero bytes, and
+  # scripts/end-intent:558 keys its exit contract on Lock.path alone. This is
+  # a requirement, not a guarantee the code enforces: the curator stray-file
+  # rule (skills/conventions/references/maintenance-and-revisions.md:155)
+  # has no *.lock carve-out today, so a wrongful delete there degrades one
+  # write window to the pre-fix (unguarded) behavior, not a hard failure.
+  def with_write_guard(intent_dir, type: "delivery",
+                       guard_timeout: WRITE_GUARD_TIMEOUT_SECONDS,
+                       guard_retry: WRITE_GUARD_RETRY_SECONDS)
+    handle = begin
+      File.open(write_guard_path(intent_dir, type: type), File::CREAT | File::RDWR, 0o644)
+    rescue SystemCallError
+      nil
+    end
+    return yield unless handle
+
+    begin
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + guard_timeout
+      begin
+        until handle.flock(File::LOCK_EX | File::LOCK_NB)
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          sleep guard_retry
+        end
+      rescue SystemCallError
+        # File#flock RAISES (does not return false) for every errno except
+        # EWOULDBLOCK, so on a filesystem where flock is unsupported (NFS,
+        # SMB, some FUSE mounts) this loop raises instead of just failing to
+        # win the lock. An flock we cannot take must degrade to an
+        # unguarded but still atomic write, same as the File.open rescue
+        # above, or this method breaks its own fail-open promise.
+        nil
+      end
+      yield
+    ensure
+      begin
+        handle.flock(File::LOCK_UN)
+      rescue SystemCallError
+        nil
+      end
+      begin
+        handle.close
+      rescue SystemCallError, IOError
+        nil
+      end
+    end
+  end
+
+  # Rewrite the lock file in place (owner-side mutations): write-to-sibling-
+  # temp plus File.rename, never an in-place truncate. POSIX rename is an
+  # atomic replace, so a concurrent reader always observes either the
+  # complete previous content or the complete new content, never a partial
+  # file. The temp file is a SIBLING in the same directory as the target,
+  # never a system tmpdir, because File.rename can raise EXDEV when the temp
+  # and the target live on different filesystems.
+  #
+  # A content write also refreshes the mtime, which is correct: every
+  # sanctioned mutation is owner activity. File.rename carries the temp
+  # file's mtime onto the target, so the post-rename mtime is "now", exactly
+  # what fresh? (above) and the hook heartbeats already assume. The rename
+  # also swaps the inode, which is safe here: heartbeat touches by path
+  # through FileUtils.touch, not by handle, and nothing in the repo holds an
+  # open handle on delivery.lock across a write.
+  #
+  # This method does NOT take the write guard itself. with_write_guard is not
+  # re-entrant, so a nested acquisition from the same process would conflict
+  # with its own outer hold and burn the entire timeout budget on every
+  # write, including the hot heartbeat path. The three read-modify-write
+  # callers take the guard around the whole sequence instead; write stays a
+  # bare atomic replace.
   def write(intent_dir, data, type: "delivery")
-    File.write(path(intent_dir, type: type), JSON.pretty_generate(data))
+    target = path(intent_dir, type: type)
+    temp = write_temp_path(intent_dir, type: type)
+    File.write(temp, JSON.pretty_generate(data))
+    File.rename(temp, target)
+  rescue StandardError
+    File.delete(temp) if temp && File.exist?(temp)
+    raise
   end
 
   # Read-only normalized inspection. The lock file and its mtime remain the