@zalom/plastic 1.0.0-beta.10 → 1.0.0-beta.12

package/PLASTIC.md

@@ -205,6 +205,26 @@ ALL work flows through intents.
 
 Hard blocking — hooks exit code 2 on gate failure.
 
+## Delivery Isolation and the Single-Owner Lock
+
+Exactly one session or agent develops an intent's delivery at a time. Ownership is the armed
+session bridge, which doubles as the delivery lock: arming records the owning session, the
+owner pid, an acquired-at timestamp, and the host. Another session that finds an armed bridge
+for the same intent with a live owner backs off; if the owner pid is dead the lock is
+reclaimable. This is mandatory, not a convention.
+
+Every code-touching intent gets its own git worktree named `{id}--{slug}`, and all code edits
+for that intent happen only inside it. Plastic provisions the worktree deterministically: it
+resolves the project repo from `projects.yml` and runs `git -C <repo> worktree add`, so
+isolation never depends on the current working directory. There are two worktrees per project
+intent: a code worktree at `<repo>/.claude/worktrees/{id}--{slug}` (branch `plastic/{id}--{slug}`)
+and a store worktree at `<plastic_home>/.worktrees/{id}--{slug}` (branch
+`plastic-store/{id}--{slug}`), so lifecycle-doc commits and code commits move as one unit.
+
+Provisioning fails open for intents that touch no project code (pure research or decision
+intents in the global store, or a non-git repo): those get the lock only, and the worktree
+block stays unprovisioned. The fail-open path is always logged, never silent.
+
 ## Deprecation Process
 
 Deprecations live in `deprecations.yml` and are shown at SessionStart. While Plastic is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.12",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-code-gate

@@ -3,11 +3,15 @@
 # frozen_string_literal: true
 
 # Usage: hook-code-gate <file_path>
-# PreToolUse gate (intent 27): when auto mode is armed and the active intent has not
-# reached How (plan.md + checklist.md), block edits to project code outside the store.
+# PreToolUse gate. Composes two independent block rules; EITHER blocks the edit:
+#   - Stage rule (intent 27): when auto mode is armed and the active intent has not
+#     reached How (plan.md + checklist.md), block edits to project code outside the store.
+#   - Worktree isolation rule (intent 73c2): when the intent has a provisioned code
+#     worktree, block project-code edits outside it; and block edits to another
+#     intent's store dir whose delivery lock is held by a live non-owner session.
 #
 # Exit 0 = allow. Exit 2 = block (reason on stderr, shown to the agent).
-# No bridge / auto not armed / How reached / path under ~/.plastic or the intent dir = allow.
+# No bridge = allow. Each rule fails open on its own conditions (see bridge.rb).
 
 require_relative "lib/bridge"
 
@@ -20,7 +24,8 @@ session = (ARGV[1] unless ARGV[1].to_s.empty?) || ENV["CLAUDE_SESSION_ID"]
 bridge_data = Bridge.discover_bridge(session: session, cwd: Dir.pwd)
 exit 0 unless bridge_data
 
-reason = Bridge.code_gate_decision(bridge_data, file_path)
+reason = Bridge.code_gate_decision(bridge_data, file_path) ||
+         Bridge.worktree_gate_decision(bridge_data, file_path, current_session: session)
 exit 0 unless reason
 
 $stderr.puts "PLASTIC GATE — #{reason}"

package/scripts/lib/bridge.rb

@@ -6,6 +6,8 @@ require "yaml"
 require "fileutils"
 require "tempfile"
 require "digest"
+require "socket"
+require_relative "worktree"
 
 module Bridge
   STAGES = %w[what why how exec done].freeze
@@ -368,6 +370,23 @@ module Bridge
         "context_pct" => 0,
         "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" => {
+        "code" => nil,
+        "code_branch" => nil,
+        "store" => nil,
+        "store_branch" => nil,
+        "provisioned" => false
+      },
+      # Delivery lock block (intent 73c). The bridge IS the lock; the owner is
+      # whoever armed it. Born unowned; arm_auto stamps owner_session/pid/etc.
+      "lock" => {
+        "owner_session" => nil,
+        "pid" => nil,
+        "acquired_at" => nil,
+        "host" => nil
       }
     }
 
@@ -439,6 +458,25 @@ module Bridge
     end
     data = derive(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
     data["build"]["auto"] = true
+
+    # Acquire the delivery lock: this armed bridge is now the single owner of the
+    # intent's delivery (intent 73c). Stamp owner + pid liveness fields.
+    data["lock"] = {
+      "owner_session" => key,
+      "pid" => Process.pid,
+      "acquired_at" => Time.now.utc.iso8601,
+      "host" => (Socket.gethostname rescue nil)
+    }
+
+    # Provision the per-intent worktrees (mandatory code worktree for project
+    # intents; fail-open for non-git / global-only). Never let a provision error
+    # break arming: the lock and auto flag still matter.
+    begin
+      Worktree.provision(data)
+    rescue => e
+      $stderr.puts "plastic: worktree provision raised, continuing unprovisioned: #{e.message}"
+    end
+
     write(key, data)
     purge_done_bridges(session: key)
     data
@@ -450,6 +488,16 @@ module Bridge
     return nil unless data
     data["build"] ||= {}
     data["build"]["auto"] = false
+
+    # Release the worktrees the matching arm provisioned (intent 73c). Non-fatal:
+    # a release error must not block disarming. CLEANUP (73c3) refines the
+    # merge-vs-remove policy on the completion/release path.
+    begin
+      Worktree.release(data)
+    rescue => e
+      $stderr.puts "plastic: worktree release raised, continuing: #{e.message}"
+    end
+
     write(session, data)
     purge_done_bridges(session: session)
     data
@@ -489,6 +537,114 @@ module Bridge
       "(blocked edit: #{file_abs})"
   end
 
+  # --- Worktree isolation gate (intent 73c2) ---
+
+  # Returns a reason String to BLOCK, or nil to ALLOW. Two independent rules,
+  # both fail-open by construction:
+  #
+  #   1. When the bridge has a provisioned code worktree, a code edit (a target
+  #      outside ~/.plastic and outside this intent's store dir) MUST land inside
+  #      worktree["code"]; otherwise BLOCK and name the expected worktree path.
+  #   2. When the target lives inside ANOTHER intent's store dir whose bridge lock
+  #      is held by a LIVE non-owner session, BLOCK (non-owner edit to an active
+  #      intent).
+  #
+  # Fails open (returns nil) when provisioned is false (non-git / global-only) or
+  # the bridge carries no worktree/lock blocks. Logs nothing on the allow path.
+  def self.worktree_gate_decision(bridge_data, file_path, home: Dir.home, current_session: nil)
+    return nil unless bridge_data.is_a?(Hash)
+    return nil if blank?(file_path)
+
+    file_abs = File.expand_path(file_path.to_s)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+    under_plastic = file_abs == plastic_home || file_abs.start_with?("#{plastic_home}/")
+
+    intent_info = bridge_data["intent"] || {}
+    store = intent_info["store"]
+    dir = intent_info["dir"]
+    intent_dir_abs = (store && dir) ? File.expand_path("#{store}/#{dir}") : nil
+    under_own_intent = intent_dir_abs &&
+                       (file_abs == intent_dir_abs || file_abs.start_with?("#{intent_dir_abs}/"))
+
+    # Rule 1: provisioned code worktree confines project-code edits.
+    worktree = bridge_data["worktree"] || {}
+    if worktree["provisioned"] == true
+      code = worktree["code"].to_s
+      # Project code = outside ~/.plastic and outside this intent's store dir.
+      is_project_code = !under_plastic && !under_own_intent
+      if is_project_code && !blank?(code)
+        code_abs = File.expand_path(code)
+        inside_code = file_abs == code_abs || file_abs.start_with?("#{code_abs}/")
+        unless inside_code
+          id = intent_info["id"]
+          return "intent #{id} is isolated to its worktree — edit project code " \
+                 "inside #{code_abs}, not the shared checkout. (blocked edit: #{file_abs})"
+        end
+      end
+    end
+
+    # Rule 2: do not edit another intent's locked, live store dir.
+    if under_plastic
+      reason = non_owner_store_edit_reason(file_abs, plastic_home, intent_dir_abs,
+                                           home: home, current_session: current_session,
+                                           own_session: bridge_data["session"])
+      return reason if reason
+    end
+
+    nil
+  end
+
+  # Helper for rule 2. A store dir is `<plastic_home>/store/{id}--{slug}` (global)
+  # or `<plastic_home>/projects/{slug}/store/{id}--{slug}` (project). When the
+  # edit target sits inside such a dir that is NOT this intent's own dir, and a
+  # live non-owner session holds that intent's bridge lock, BLOCK.
+  def self.non_owner_store_edit_reason(file_abs, plastic_home, own_intent_dir_abs,
+                                       home:, current_session:, own_session:)
+    return nil if own_intent_dir_abs &&
+                  (file_abs == own_intent_dir_abs || file_abs.start_with?("#{own_intent_dir_abs}/"))
+
+    parsed = parse_store_target(file_abs, plastic_home)
+    return nil unless parsed
+
+    session = blank?(current_session) ? own_session : current_session
+    held = Worktree.lock_held_by_other?(
+      intent_id: parsed[:id], store: parsed[:store],
+      current_session: session, home: home,
+    )
+    return nil unless held
+
+    "intent #{parsed[:id]} is owned by another live session — its delivery lock " \
+      "is held elsewhere. Back off; do not edit #{file_abs}."
+  end
+
+  # Resolve an edit target inside a store to {id:, store:} for the intent dir it
+  # belongs to, or nil if the path is not inside an `{id}--{slug}` intent dir.
+  def self.parse_store_target(file_abs, plastic_home)
+    rels = []
+    global_store = File.join(plastic_home, "store")
+    if file_abs.start_with?("#{global_store}/")
+      rels << [file_abs[(global_store.length + 1)..], global_store]
+    end
+    projects = File.join(plastic_home, "projects")
+    if file_abs.start_with?("#{projects}/")
+      tail = file_abs[(projects.length + 1)..].to_s
+      parts = tail.split(File::SEPARATOR)
+      if parts.length >= 2 && parts[1] == "store"
+        pstore = File.join(projects, parts[0], "store")
+        rels << [file_abs[(pstore.length + 1)..], pstore]
+      end
+    end
+
+    rels.each do |rel, store_dir|
+      next if blank?(rel)
+      first = rel.split(File::SEPARATOR).first.to_s
+      idx = first.index("--")
+      next unless idx && idx > 0
+      return { id: first[0...idx], store: store_dir }
+    end
+    nil
+  end
+
   # --- Bash-edit gate (intent 27a) ---
 
   # Extract the set of file paths a Bash command writes to. Conservative by

package/scripts/lib/installer_core.rb

@@ -210,6 +210,7 @@ class InstallerCore
       "scripts/hook-bash-gate" => "scripts/hook-bash-gate",
       "scripts/hook-auto-arm" => "scripts/hook-auto-arm",
       "scripts/lib/bridge.rb" => "scripts/lib/bridge.rb",
+      "scripts/lib/worktree.rb" => "scripts/lib/worktree.rb",
       "scripts/lib/boot_banner.rb" => "scripts/lib/boot_banner.rb",
       "scripts/lib/qmd_sync.rb" => "scripts/lib/qmd_sync.rb",
       "scripts/qmd-sync" => "scripts/qmd-sync",

package/scripts/lib/worktree.rb

@@ -0,0 +1,409 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "socket"
+require "time"
+
+# Worktree -- Plastic-supplied git worktree isolation and the delivery lock
+# (intent 73c / 73c1).
+#
+# The harness `EnterWorktree` tool assumes cwd IS the repo root, which is false
+# for Plastic (cwd is often the parent of the repo subdir). When the mismatch
+# occurs the tool silently degrades to a plain feature branch on the shared
+# checkout, so parallel intent deliveries are NOT isolated. This module makes
+# isolation deterministic and cwd-independent: Plastic resolves the repo from
+# projects.yml and runs `git -C <repo> worktree add`, so the cwd-not-root bug
+# dies by construction (decision D6).
+#
+# Two worktrees per project intent, both named `{id}--{slug}` (decision D2):
+#   code  worktree  <repo>/.claude/worktrees/{id}--{slug}  branch plastic/{id}--{slug}
+#   store worktree  <plastic_home>/.worktrees/{id}--{slug} branch plastic-store/{id}--{slug}
+#
+# The bridge file doubles as the delivery lock (decision D3): single-owner,
+# stale-lock reclaim via pid liveness.
+#
+# Pure and dependency-injected: every git call goes through an injected
+# `ShellRunner`, so unit tests are hermetic (no real git; inject a fake runner).
+# No eval, no global/ENV config injection.
+module Worktree
+  module_function
+
+  # --- ShellRunner (DI seam) -------------------------------------------------
+
+  # The default runner shells out to real `git`. Tests inject a fake with the
+  # same `run(*args)` contract so no real git runs in unit tests.
+  class ShellRunner
+    Result = Struct.new(:status, :stdout, :stderr) do
+      def success?
+        status.zero?
+      end
+    end
+
+    def run(*args)
+      require "open3"
+      out, err, status = Open3.capture3("git", *args.map(&:to_s))
+      Result.new(status.exitstatus.to_i, out, err)
+    end
+  end
+
+  # --- pure helpers ----------------------------------------------------------
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  # The `{id}--{slug}` identity shared by both worktrees and both branches.
+  def dir_name(intent_id, intent_slug)
+    "#{intent_id}--#{intent_slug}"
+  end
+
+  # Pure, deterministic. Returns the four paths/branches. No git calls.
+  # `repo_path` is resolved from projects.yml when nil; when it cannot be
+  # resolved the code worktree path/branch are nil (a global-store-only intent).
+  def paths(slug:, intent_id:, intent_slug:, home: Dir.home, repo_path: nil)
+    name = dir_name(intent_id, intent_slug)
+    repo = repo_path || repo_for(slug, home: home)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+
+    code_path = repo ? File.join(File.expand_path(repo), ".claude", "worktrees", name) : nil
+    store_path = File.join(plastic_home, ".worktrees", name)
+
+    {
+      "code" => code_path,
+      "code_branch" => code_path ? "plastic/#{name}" : nil,
+      "store" => store_path,
+      "store_branch" => "plastic-store/#{name}",
+    }
+  end
+
+  # Absolute repo path for a project slug from `~/.plastic/projects.yml`, or nil.
+  # Reuses the qmd_sync safe-loader pattern: any failure yields nil.
+  def repo_for(slug, home: Dir.home)
+    return nil if blank?(slug)
+    projects = load_projects(home)
+    info = projects[slug.to_s]
+    path = info.is_a?(Hash) ? info["path"] : nil
+    return nil if blank?(path)
+    File.expand_path(path)
+  end
+
+  # --- provisioning ----------------------------------------------------------
+
+  # Resolve the slug from the bridge's intent.store, create code + store
+  # worktrees (idempotent: reuse an existing worktree path, do not error), write
+  # the `worktree` block plus `provisioned: true` onto bridge_data, return it.
+  #
+  # Fails open with a stderr log when the repo is non-git or unresolvable:
+  # sets `provisioned: false` and leaves `code: null`. All git ops use
+  # `git -C <resolved path>` -- never cwd (decision D6).
+  def provision(bridge_data, home: Dir.home, runner: ShellRunner.new)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    intent = bridge_data["intent"] || {}
+    intent_id = intent["id"].to_s
+    store = intent["store"].to_s
+    intent_slug = slug_from_dir(intent["dir"]) || slug_from_dir(store)
+
+    slug = slug_for_store(store, home: home)
+    p = paths(slug: slug, intent_id: intent_id, intent_slug: intent_slug, home: home)
+
+    block = {
+      "code" => nil,
+      "code_branch" => nil,
+      "store" => p["store"],
+      "store_branch" => p["store_branch"],
+      "provisioned" => false,
+    }
+
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+
+    # Gitignore safety (intent 73c3): the store worktrees live under the store git
+    # repo, so without ignoring `.worktrees/` a `git add -A` sweeps their gitlinks
+    # into the store commit. Ensure both ignore entries before any worktree add.
+    ensure_gitignored(plastic_home, ".worktrees/", runner: runner)
+
+    # Store worktree: created against the plastic home git repo. Fail-open if the
+    # store repo is not a git repo (a fresh global store may be ungit'd).
+    store_ok = add_worktree(runner, repo: plastic_home,
+                            worktree: p["store"], branch: p["store_branch"],
+                            label: "store")
+
+    # Code worktree: MANDATORY for project intents. Fail-open when the repo is
+    # unresolvable or non-git -- that is the global-store-only / non-git case.
+    repo = repo_for(slug, home: home)
+    code_ok = false
+    if repo && git_repo?(runner, repo)
+      ensure_gitignored(repo, ".claude/worktrees/", runner: runner)
+      code_ok = add_worktree(runner, repo: repo,
+                             worktree: p["code"], branch: p["code_branch"],
+                             label: "code")
+      if code_ok
+        block["code"] = p["code"]
+        block["code_branch"] = p["code_branch"]
+      end
+    else
+      warn "plastic: worktree provision fail-open -- repo for slug #{slug.inspect} " \
+           "is unresolvable or not a git repo; code worktree skipped"
+    end
+
+    block["store"] = store_ok ? p["store"] : nil
+    block["store_branch"] = store_ok ? p["store_branch"] : nil
+
+    # provisioned is true only when the MANDATORY code worktree exists. The gate
+    # fails open on provisioned: false (non-git / global-only).
+    block["provisioned"] = code_ok
+
+    bridge_data["worktree"] = block
+    bridge_data
+  end
+
+  # Remove both worktrees (then `git worktree prune`), clear the worktree block.
+  # No-op when nothing was provisioned. CLEANUP (73c3) layers the merge-vs-remove
+  # policy on top via `finish`; this is the plain remove. Pass `remove: false` to
+  # clear the block WITHOUT touching git (so `finish` can merge first, then call
+  # release to drop the worktrees once the code branch is integrated).
+  def release(bridge_data, home: Dir.home, runner: ShellRunner.new, remove: true)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    block = bridge_data["worktree"]
+    return bridge_data unless block.is_a?(Hash)
+
+    if remove
+      plastic_home = File.expand_path(File.join(home, ".plastic"))
+      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      repo = repo_for(slug, home: home)
+
+      remove_worktree(runner, repo: repo, worktree: block["code"]) if repo && block["code"]
+      remove_worktree(runner, repo: plastic_home, worktree: block["store"]) if block["store"]
+
+      prune(runner, repo: repo) if repo
+      prune(runner, repo: plastic_home)
+    end
+
+    bridge_data.delete("worktree")
+    bridge_data
+  end
+
+  # --- cleanup policy (merge-vs-remove) -------------------------------------
+
+  # Finish an intent's delivery by tearing down its worktrees, optionally merging
+  # the code branch back first (intent 73c3). The merge-vs-remove decision is the
+  # one piece of policy on top of the plain `release`:
+  #
+  #   merge: true  -> the releasing path. Merge the intent's code branch
+  #                   (`plastic/{id}--{slug}`) into the repo's default branch
+  #                   BEFORE removing the worktrees, so the work is integrated and
+  #                   not lost when the worktree disappears. Then `release`.
+  #   merge: false -> the disarm / abandon path. Just `release` (plain remove);
+  #                   the branch survives and can be reclaimed.
+  #
+  # Fail-open and idempotent throughout: a missing block, missing branch, or any
+  # git failure never raises and never blocks teardown. All git ops use
+  # `git -C <path>`, never cwd (decision D6). No-op when nothing was provisioned.
+  def finish(bridge_data, home: Dir.home, runner: ShellRunner.new, merge: false)
+    return bridge_data unless bridge_data.is_a?(Hash)
+    block = bridge_data["worktree"]
+    return bridge_data unless block.is_a?(Hash)
+
+    if merge
+      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      repo = repo_for(slug, home: home)
+      branch = block["code_branch"]
+      merge_branch(runner, repo: repo, branch: branch) if repo && !blank?(branch)
+    end
+
+    release(bridge_data, home: home, runner: runner, remove: true)
+  end
+
+  # Merge `branch` into the repo's default branch from the main checkout. The
+  # worktree the branch is checked out in stays put; we merge in the repo dir
+  # itself (its own current branch is the integration target). Idempotent: a
+  # no-op merge ("Already up to date") still succeeds. Fail-open: a conflicting
+  # or otherwise failing merge is aborted and logged, never raised, so teardown
+  # still proceeds (CLEANUP must not strand a worktree).
+  def merge_branch(runner, repo:, branch:)
+    return false if blank?(repo) || blank?(branch)
+    target = current_branch(runner, repo: repo)
+    return false if blank?(target) || target == branch
+
+    res = runner.run("-C", repo, "merge", "--no-ff", "--no-edit", branch)
+    return true if res.success?
+
+    # Leave the integration branch clean: abort a half-applied/conflicted merge.
+    runner.run("-C", repo, "merge", "--abort")
+    warn "plastic: worktree finish could not merge #{branch.inspect} into " \
+         "#{target.inspect}: #{res.stderr.to_s.strip}; removing worktree without merge"
+    false
+  end
+
+  # The repo's current branch (the integration target), or nil when detached /
+  # unresolvable.
+  def current_branch(runner, repo:)
+    return nil if blank?(repo)
+    res = runner.run("-C", repo, "rev-parse", "--abbrev-ref", "HEAD")
+    return nil unless res.success?
+    name = res.stdout.to_s.strip
+    (name.empty? || name == "HEAD") ? nil : name
+  end
+
+  # --- gitignore safety ------------------------------------------------------
+
+  # Ensure `entry` is present in `<repo>/.gitignore`, appending it once if absent
+  # (idempotent). Without this, the store worktrees that live UNDER the store git
+  # repo (~/.plastic/.worktrees/) get swept into the store commit by a `git add
+  # -A`, polluting the index with worktree gitlinks (observed during 73c1
+  # integration). Provisioning and cleanup both call this so the repos' indexes
+  # stay clean. Best-effort and non-raising: any failure is logged, never raised.
+  def ensure_gitignored(repo, entry, runner: ShellRunner.new)
+    return false if blank?(repo) || blank?(entry) || !Dir.exist?(repo)
+    gitignore = File.join(File.expand_path(repo), ".gitignore")
+    want = entry.to_s.strip
+
+    existing = File.exist?(gitignore) ? File.read(gitignore) : ""
+    present = existing.each_line.any? { |line| line.strip == want }
+    return true if present
+
+    File.open(gitignore, "a") do |io|
+      io.write("\n") unless existing.empty? || existing.end_with?("\n")
+      io.write("#{want}\n")
+    end
+    true
+  rescue StandardError => e
+    warn "plastic: ensure_gitignored(#{entry.inspect}) failed for #{repo.inspect}: #{e.message}"
+    false
+  end
+
+  # --- lock ------------------------------------------------------------------
+
+  # pid liveness: signal 0 probes without sending. Any error (no such process,
+  # not ours) means not live.
+  def session_live?(pid)
+    n = Integer(pid) rescue nil
+    return false if n.nil? || n <= 0
+    Process.kill(0, n)
+    true
+  rescue StandardError
+    false
+  end
+
+  # True iff ANOTHER bridge for this intent has a LIVE owner pid that is not
+  # current_session. Scans /tmp/plastic-*.json (or `tmp`). The current session's
+  # own bridge never counts as "other". A dead owner does not hold the lock
+  # (stale-lock reclaim).
+  def lock_held_by_other?(intent_id:, store:, current_session:, home: Dir.home, tmp: nil)
+    tmp ||= default_tmp
+    id = intent_id.to_s
+    st = File.expand_path(store.to_s) unless blank?(store)
+
+    Dir.glob(File.join(tmp, "plastic-*.json")).each do |f|
+      next if f.end_with?(".tmp")
+      data = (JSON.parse(File.read(f)) rescue nil)
+      next unless data.is_a?(Hash)
+
+      intent = data["intent"] || {}
+      next unless intent["id"].to_s == id
+      unless st.nil?
+        bstore = intent["store"].to_s
+        next unless bstore.empty? || File.expand_path(bstore) == st
+      end
+
+      session = data["session"].to_s
+      next if !blank?(current_session) && session == current_session.to_s
+
+      lock = data["lock"] || {}
+      owner_pid = lock["pid"]
+      return true if session_live?(owner_pid)
+    end
+    false
+  rescue StandardError
+    false
+  end
+
+  # --- git operations (all use -C, never cwd) --------------------------------
+
+  # Idempotent worktree add. If `worktree` already exists on disk, treat as
+  # reuse (success, no git call). Otherwise `git -C <repo> worktree add <wt>
+  # -b <branch>`; if the branch already exists, retry without -b (reattach).
+  def add_worktree(runner, repo:, worktree:, branch:, label:)
+    return false if blank?(repo) || blank?(worktree)
+    return true if Dir.exist?(worktree) # idempotent reuse
+
+    res = runner.run("-C", repo, "worktree", "add", worktree, "-b", branch)
+    return true if res.success?
+
+    # Branch may already exist (a prior provision that was pruned but kept the
+    # branch). Retry attaching the existing branch.
+    res2 = runner.run("-C", repo, "worktree", "add", worktree, branch)
+    return true if res2.success?
+
+    warn "plastic: worktree add (#{label}) failed: #{res.stderr.to_s.strip}"
+    false
+  end
+
+  def remove_worktree(runner, repo:, worktree:)
+    return false if blank?(repo) || blank?(worktree)
+    res = runner.run("-C", repo, "worktree", "remove", worktree)
+    unless res.success?
+      # Force-remove tolerates dirty/locked worktrees; CLEANUP owns merge policy.
+      res = runner.run("-C", repo, "worktree", "remove", "--force", worktree)
+    end
+    res.success?
+  end
+
+  def prune(runner, repo:)
+    return false if blank?(repo)
+    runner.run("-C", repo, "worktree", "prune").success?
+  end
+
+  # True iff `repo` is a git work tree (idempotent, no mutation).
+  def git_repo?(runner, repo)
+    return false if blank?(repo) || !Dir.exist?(repo)
+    res = runner.run("-C", repo, "rev-parse", "--is-inside-work-tree")
+    res.success? && res.stdout.to_s.strip == "true"
+  end
+
+  # --- internals (projects.yml resolution, mirrors qmd_sync) -----------------
+
+  def load_projects(home)
+    path = File.join(File.expand_path(home), ".plastic", "projects.yml")
+    return {} unless File.exist?(path)
+    data = begin
+      YAML.safe_load(File.read(path)) || {}
+    rescue StandardError
+      {}
+    end
+    projects = data.is_a?(Hash) ? data["projects"] : nil
+    projects.is_a?(Hash) ? projects : {}
+  end
+
+  # Resolve a project slug from a store directory. A project's tactical store
+  # lives at <plastic_home>/projects/<slug>/store; the global store yields nil
+  # (no project repo). Mirrors qmd_sync's slug_for_store fallback.
+  def slug_for_store(store_dir, home: Dir.home)
+    return nil if blank?(store_dir)
+    plastic_home = File.expand_path(File.join(home, ".plastic"))
+    store_dir = File.expand_path(store_dir)
+    return nil if store_dir == File.join(plastic_home, "store")
+
+    parts = store_dir.split(File::SEPARATOR)
+    idx = parts.rindex("projects")
+    return parts[idx + 1] if idx && parts[idx + 1] && parts[idx + 2] == "store"
+    nil
+  end
+
+  # Best-effort slug for the worktree dir-name from an intent dir/store path:
+  # the basename `{id}--{slug}` -> the `{slug}` portion (split on the first
+  # `--`). Used only for naming.
+  def slug_from_dir(dir)
+    return nil if blank?(dir)
+    base = File.basename(dir.to_s)
+    idx = base.index("--")
+    return nil unless idx
+    base[(idx + 2)..]
+  end
+
+  def default_tmp
+    t = ENV["PLASTIC_TMP"]
+    (t.nil? || t.strip.empty?) ? "/tmp" : t
+  end
+end

package/skills/auto/SKILL.md

@@ -43,13 +43,18 @@ edited before the plan exists (the gate applies to YOU, the orchestrator):
 
 ```bash
 ruby -r ~/.plastic/scripts/lib/bridge -e \
-  'Bridge.arm_auto(ENV["CLAUDE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
+  'Bridge.arm_auto(ENV["CLAUDE_CODE_SESSION_ID"], intent_id: "<ID>", intent_dir: "<STORE>/<dir>", store: "<STORE>", name: "<name>")'
 ```
 
 Replace `<ID>`, `<STORE>` (e.g. `~/.plastic/projects/<slug>/store` or `~/.plastic/store`),
-`<dir>` (the `ID--slug` directory), and `<name>`. If `CLAUDE_SESSION_ID` is unset, `arm_auto`
-falls back to a deterministic derived bridge key (a hash of the store and intent id), so the
-gate still engages; arming prints a one-line notice to stderr in that case.
+`<dir>` (the `ID--slug` directory), and `<name>`. The first argument is the session id you
+want the bridge keyed by: pass the hook stdin `session_id` when you have it, otherwise
+`ENV["CLAUDE_CODE_SESSION_ID"]`, otherwise `nil`. `arm_auto` calls `resolve_session`, which
+picks the first non-empty of: the explicit id you pass -> `CLAUDE_SESSION_ID` ->
+`CLAUDE_CODE_SESSION_ID` -> a deterministic derived key (a hash of the store and intent id).
+It never returns nil, so the gate engages even when every session env var is empty; the call
+never needs a non-empty `CLAUDE_SESSION_ID` to function. Arming prints a one-line notice to
+stderr when it falls through to the derived key.
 
 **Hard rule for the rest of this run:** do NOT edit project code (anything outside the
 intent directory / `~/.plastic/`) until `plan.md` AND `checklist.md` exist for the intent.
@@ -79,7 +84,7 @@ Completion report (require-then-synthesize): every dispatched specialist MUST en
 
 Final-gate review: dispatch an independent reviewer subagent at the final gate only, not as a standing role.
 
-Headless manual gate: when running headless or in the background, enforce gates manually and do not rely on hooks, because `CLAUDE_SESSION_ID` may be unset (this ties to the arm-gate fallback above).
+Headless manual gate: when running headless or in the background, still enforce gates manually rather than relying on hooks alone. The PostToolUse gate hook reads `session_id` from hook stdin, and the savepoint ledger write is decoupled from the bridge (derived from the file path, so it fires even with no session id) - these do NOT no-op. What can degrade is the bridge-keyed stage enforcement: if no session id reaches the bridge and no matching bridge is discovered, the stage-gate enforcement step exits without acting, so verify state yourself. The bridge still resolves arming via `CLAUDE_CODE_SESSION_ID` or the derived-key fallback (see the arm-gate note above).
 
 Solo fallback: if the harness has no subagent dispatch, fall back to a single agent walking the full What, Why, How, Exec cycle yourself. This preserves current behavior.
 
@@ -202,10 +207,24 @@ During initial project creation, all decisions are non-destructive by definition
    store that holds this intent (the global store or the project store).
 9. Disarm the lifecycle gate (auto delivery is finished):
    ```bash
-   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_SESSION_ID"])'
+   ruby -r ~/.plastic/scripts/lib/bridge -e 'Bridge.disarm_auto(ENV["CLAUDE_CODE_SESSION_ID"])'
    ```
    Disarming also purges stale bridge files from the temp directory automatically (it keeps the
    current bridge and any live run), so no manual `/tmp` cleanup is needed.
+
+   **Worktree cleanup (mandatory, intent 73c3).** Disarming performs the worktree release:
+   `disarm_auto` calls `Worktree.release`, which removes both per-intent worktrees (the code
+   worktree under `<repo>/.claude/worktrees/{id}--{slug}` and the paired store worktree under
+   `<plastic_home>/.worktrees/{id}--{slug}`), prunes both repos, and clears the worktree block
+   from the bridge. This is the plain remove path: the disarm route does NOT merge, so use it
+   only when no release merges the branch (the branch survives and can be reclaimed).
+
+   When the work is being shipped through a release, do NOT rely on this plain remove. The
+   release path (step 4 above, via `plastic-releasing`) is responsible for merging the intent's
+   code branch (`plastic/{id}--{slug}`) back to the repo's default branch BEFORE the worktree is
+   removed, so the integrated work is not lost. It does this with `Worktree.finish(bridge_data,
+   merge: true)` (merge-then-remove). Never leave an orphaned worktree, and run `git worktree
+   prune` if you hit a stale reference.
 10. Notify user: "Intent [ID] — [name] delivered. [1-2 sentence summary]. See outcome.md for details."
 
 ## Error Handling

package/skills/auto/references/agent-architecture.md

@@ -90,10 +90,13 @@ permanent sixth role, it exists only for the final review.
 
 ### Headless Manual Gate
 
-When running headless or in the background, the enforcer enforces gates manually and
-does not rely on hooks, because `CLAUDE_SESSION_ID` may be unset in those runs (the
-gate-check and savepoint hooks no-op without it). The enforcer arms via the bridge's
-derived-key fallback and verifies state itself.
+When running headless or in the background, the enforcer enforces gates manually rather
+than relying on hooks alone. The savepoint ledger and PostToolUse gate hook still fire
+(the gate hook reads `session_id` from stdin; the savepoint write is path-derived and
+bridge-independent), so they do not blanket no-op. Only the bridge-keyed stage-enforcement
+step degrades when no session id reaches the bridge and no bridge is discovered. The
+enforcer arms via `CLAUDE_CODE_SESSION_ID` or the bridge's derived-key fallback and
+verifies state itself.
 
 ### Delegation
 

package/skills/releasing/SKILL.md

@@ -20,6 +20,7 @@ Project configuration drives the workflow - no hardcoded assumptions.
 - [ ] Run post-push actions (GitHub release, npm publish, etc.)
 - [ ] Verify release sync (npm dist-tag, GitHub "Latest", git tag all show the new version)
 - [ ] Complete active intent
+- [ ] Clean up the intent's worktrees (merge-then-remove)
 
 ## Workflow
 
@@ -84,6 +85,15 @@ git merge <branch-name> --no-ff -m "feat: merge intent [ID] - [description]"
 
 Always `--no-ff` to preserve branch history in the merge commit.
 
+**Worktree-isolated intents (intent 73c3).** When the intent was delivered in a Plastic
+worktree (the bridge has a provisioned `worktree` block), its code lives on the branch
+`plastic/{id}--{slug}` inside `<repo>/.claude/worktrees/{id}--{slug}`, not on a hand-made
+feature branch. The merge-then-remove of that worktree is handled together with cleanup in
+step 9, which merges `plastic/{id}--{slug}` into the default branch BEFORE removing the
+worktree. If you already merged here by hand, step 9 is a clean no-op merge ("Already up to
+date") and proceeds straight to removal. Do not delete the worktree before its branch is
+merged, or the work is lost.
+
 ### 4. Bump Version
 
 Determine which files to update from project.yml:
@@ -207,6 +217,28 @@ A release IS a delivery. The active intent that drove this work must be complete
 
 **If no active intent exists for this release**, that itself is a problem - work happened outside the intent system. Log it and move on, but flag it.
 
+### 9. Clean Up the Intent's Worktrees (merge-then-remove)
+
+A release is the merge-then-remove path for the intent's worktrees (intent 73c3). This is the
+one place the merge-vs-remove policy lands on "merge": the intent's code branch
+(`plastic/{id}--{slug}`) is merged back into the repo's default branch BEFORE the worktree is
+removed, so the integrated work is never lost. (The disarm path in `plastic-auto`, by contrast,
+is a plain remove because no release is merging the branch.)
+
+Drive it through `Worktree.finish` with `merge: true`, which merges the code branch, then
+removes both worktrees (code + paired store), prunes both repos, and clears the worktree block
+from the bridge:
+
+```bash
+ruby -r ~/.plastic/scripts/lib/worktree -r ~/.plastic/scripts/lib/bridge -e \
+  'b = Bridge.read(ENV["CLAUDE_CODE_SESSION_ID"]); Worktree.finish(b, merge: true) if b'
+```
+
+`finish` is fail-open and idempotent: a conflicting merge is aborted and logged (the worktree
+is still removed rather than stranded), and a second call with the block already cleared is a
+no-op. Honor the worktree-cleanup rule: never leave an orphaned worktree, and run `git worktree
+prune` in the affected repo if you hit a stale reference.
+
 ## Conventions
 
 - **Annotated tags only** - `git tag -a`, never lightweight tags