@zalom/plastic 1.14.1 → 2.0.0-alpha.10

package/scripts/hook-session-start

@@ -6,14 +6,36 @@
 require "json"
 require "date"
 require "yaml"
+require "fileutils"
 require_relative "lib/bridge"
+require_relative "lib/savepoint"
 require_relative "lib/boot_banner"
 require_relative "lib/qmd_sync"
 require_relative "lib/doctor_core"
+require_relative "lib/session_ledger"
+require_relative "lib/day_summary"
 
 index_path, plastic_home, mode, plugin_root = ARGV
 exit 0 unless index_path && plastic_home && mode
 
+# --- session id: the stdin payload's session_id, then the env var, then the
+# pid (spec 298 D1, row G, spec D4). Guarded on $stdin.tty? so a human running
+# this hook by hand at a real terminal never blocks on a read that never gets
+# an EOF; every real harness invocation pipes the SessionStart JSON payload,
+# never attaches a tty. Malformed or empty stdin (or no payload id) falls
+# through to the same env-var-then-pid chain this always had.
+stdin_payload = begin
+  if $stdin.tty?
+    nil
+  else
+    raw = $stdin.read
+    raw && !raw.strip.empty? ? JSON.parse(raw) : nil
+  end
+rescue StandardError
+  nil
+end
+payload_session_id = stdin_payload.is_a?(Hash) ? stdin_payload["session_id"].to_s : ""
+
 # Plastic home and the store are two different paths (intent 231). The shim passes
 # home (~/.plastic) as argument 2; the store lives one level below it. Compose the
 # store exactly once here, so no later line re-derives it and no path can gain a
@@ -48,16 +70,20 @@ lines.each do |line|
   end
 end
 
-# --- Derive bridge for active intent ---
+# --- Stage of the single active intent (the /tmp bridge this once derived was removed in 2.0, intent 307) ---
 
-bridge_data = nil
+stage_line = nil
 if active.length == 1 && active.first =~ /store\/([\w-]+)\//
   dir_name = $1
   intent_dir = "#{store_dir}/#{dir_name}"
-  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
-  intent_id = dir_name.split("--").first
-  intent_name = active.first[/\[([^\]]+)\]/, 1] || "unknown"
-  bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_dir, name: intent_name)
+  begin
+    stage = Savepoint.derive_stage(intent_dir)
+    missing = Savepoint.missing_for_stage(stage, intent_dir)
+    missing_str = missing.empty? ? "none" : missing.join(", ")
+    stage_line = "Stage: #{stage} | Next: #{missing_str}"
+  rescue StandardError
+    stage_line = nil
+  end
 end
 
 # --- Detect stale future intents ---
@@ -251,12 +277,7 @@ if plastic_md
   if all_active.any?
     parts << "Active intents:\n"
     all_active.each { |a| parts << a }
-    if bridge_data
-      stage = bridge_data["build"]["stage"]
-      missing = bridge_data["build"]["missing"]
-      missing_str = missing.empty? ? "none" : missing.join(", ")
-      parts << "Stage: #{stage} | Next: #{missing_str}"
-    end
+    parts << stage_line if stage_line
     parts << ""
   else
     parts << "No active intents. #{future.length} future intents available.\n"
@@ -302,6 +323,101 @@ if update_notice
   parts.unshift("! #{update_notice}\n")
 end
 
+# --- First-boot sweep (intent 301, spec D9): file every unclosed prior day
+# ledger into today, oldest first, at most 3 per boot within a 5-second
+# budget. Each day runs the sibling file-session-intent in its own rescue;
+# the boot never blocks on it.
+begin
+  require "open3"
+  require "timeout"
+  require_relative "lib/session_backfill"
+
+  sweep_today = SessionLedger.day_id
+  sweep_root = SessionLedger.sessions_root(store_dir)
+  sweep_filer = File.expand_path("file-session-intent", __dir__)
+  sweep_templates = File.expand_path("../templates", __dir__)
+  candidates = []
+  if Dir.exist?(sweep_root) && File.exist?(sweep_filer)
+    candidates = Dir.children(sweep_root).select do |name|
+      File.directory?(File.join(sweep_root, name)) && SessionLedger.valid_day_id?(name) &&
+        name < sweep_today && !SessionBackfill.closed?(store_dir, name)
+    end.sort
+  end
+  filed = 0
+  budget_end = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
+  candidates.first(3).each do |day|
+    break if Process.clock_gettime(Process::CLOCK_MONOTONIC) > budget_end
+
+    begin
+      Timeout.timeout(5) do
+        _out, _err, sweep_status = Open3.capture3({ "RUBYOPT" => nil }, RbConfig.ruby, sweep_filer,
+                                                  "--day", day, "--carry-to", sweep_today,
+                                                  "--store", store_dir, "--templates", sweep_templates)
+        filed += 1 if sweep_status.success? && SessionBackfill.closed?(store_dir, day)
+      end
+    rescue StandardError
+      nil
+    end
+  end
+  if filed.positive?
+    line = "PLASTIC: filed #{filed} prior day ledger(s) into #{sweep_today}"
+    remaining = candidates.size - filed
+    line += ", #{remaining} more wait for the next boot" if remaining.positive?
+    parts << line
+  end
+rescue StandardError
+  nil
+end
+
+# --- Session day ledger: open or join today, write the per-session pointer
+# and heartbeat (intent 298, spec D4). Best-effort: any failure here degrades
+# to no ledger context line, never blocks the session.
+begin
+  templates = File.expand_path("../templates", __dir__)
+  day = SessionLedger.day_id
+  author = `"#{read_config}" author`.strip
+  author = "session" if author.empty?
+  SessionLedger.open_day(store: store_dir, day: day, templates: templates, author: author)
+
+  session = if !payload_session_id.empty?
+              payload_session_id
+            else
+              ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
+            end
+  sid = SessionLedger.short_session_id(nil, session)
+  SessionLedger.ensure_tmp_root(store_dir)
+  FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store_dir, sid))
+  File.write(SessionLedger.heartbeat_path(store_dir, sid), "#{Time.now.utc.iso8601}\n")
+  pointer = SessionLedger.pointer_path(store_dir, sid)
+  File.write(pointer, "#{day}\n") unless File.exist?(pointer)
+
+  checklist = SessionLedger.checklist_path(store_dir, day)
+  open_count = 0
+  pending_count = 0
+  if File.exist?(checklist)
+    File.readlines(checklist).each do |line|
+      parsed = SessionLedger.parse_checklist_line(line)
+      next unless parsed
+
+      open_count += 1 if parsed[:state] == :open
+      pending_count += 1 if parsed[:state] == :pending
+    end
+  end
+  parts << "PLASTIC: day ledger #{day} joined (#{open_count} open items, #{pending_count} pending)"
+
+  # The day summary (intent 311, spec D8): open items, the last five done,
+  # live auto intents, other active sessions. Never the raw ledger. A
+  # failure here leaves the joined line alone.
+  begin
+    summary = DaySummary.build(store: store_dir, day: day, session: sid, home: plastic_home, now: Time.now)
+    parts << summary unless summary.empty?
+  rescue StandardError
+    nil
+  end
+rescue StandardError
+  nil
+end
+
 # Emit nothing when there is genuinely nothing to surface (no conventions,
 # no deprecations, no update notice).
 exit 0 if parts.join.strip.empty?

package/scripts/install.rb

@@ -3,7 +3,11 @@
 # frozen_string_literal: true
 
 # Plastic — `install` verb. Runs via `npx @zalom/plastic install` (bin/plastic.js) or directly.
-# Usage: ruby scripts/install.rb [--claude|--codex|--hermes|--all] [--alpha|--beta|--latest] [--reinstall] [--force] [--help]
+# Usage: ruby scripts/install.rb [--claude|--codex|--hermes|--all] [--reinstall] [--force] [--help]
+#
+# The package version selects the channel: `npx @zalom/plastic@alpha install --claude` (or
+# a pinned `@2.0.0-alpha.1`). The channel flags this verb once listed never selected a
+# package and were removed in 2.0 (intent 310).
 #
 # One-shot by design:
 #   - no install present  -> fresh install + bootstrap store
@@ -206,7 +210,7 @@ class Install < InstallerCore
     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"
+    puts "   Plastic's hooks will not fire until you do.\n\n"
   end
 
   def show_help
@@ -223,10 +227,8 @@ class Install < InstallerCore
         --hermes      Install for Hermes
         --all         Install for all supported agents
 
-      Channel options:
-        --latest      Stable channel (default)
-        --beta        Beta channel
-        --alpha       Alpha channel
+      Channel: pin the package, e.g. `npx @zalom/plastic@alpha install --claude`
+        (@latest is stable and the default; @beta and @alpha are the other channels)
 
       Other options:
         --reinstall          Re-sync core files for the installed version (repair). Store untouched.

package/scripts/intent-screen

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+# intent-screen (intent 316) - prints the intent screen for one intent directory:
+# the title, the field table (Store, Status, Stage, Savepoint, Progress, Next,
+# Insight, each with a note), and the Steps table, filled from the record by
+# scripts/lib/intent_screen.rb. The session adds the What-this-means bullets and
+# the close; it never edits the numbers.
+#
+# Usage:
+#   intent-screen <intent_dir> [--template <path>] [--ansi]
+#
+# The store root is the directory two levels above the intent (<root>/store/<id--slug>);
+# the template defaults to templates/intent-screen.md next to this script's dir,
+# in-repo (<repo>/scripts -> <repo>/templates) and installed (~/.plastic/scripts ->
+# ~/.plastic/templates) alike.
+#
+# --ansi (intent 316a, O3): emits scripts/lib/intent_screen_ansi.rb's styled
+# truecolor block instead of the plain Markdown screen. Plain stays the
+# default with no flag. Two things force plain even WITH --ansi (D18): NO_COLOR
+# present in the environment (any value counts), or a non-TTY stdout — the
+# true default form of D2, not IntentScreenAnsi's own uncoloured layout. The
+# library (scripts/lib/intent_screen_ansi.rb) is pure and never reads either;
+# this script is the one place allowed to.
+#
+# Exit codes:
+#   0 - the screen is on stdout
+#   2 - usage error, or the path is not an intent directory (one line on stderr)
+#
+# Harness-agnostic core: no harness assumption lives here. This script holds
+# the plain/ANSI selection (intent 316a1, D3) and belongs to the same
+# harness-agnostic core as lib/intent_screen.rb and lib/intent_screen_ansi.rb.
+
+require_relative "lib/intent_screen"
+require_relative "lib/intent_screen_ansi"
+
+def usage_abort(message)
+  warn "intent-screen: #{message}"
+  exit 2
+end
+
+args = ARGV.dup
+template_path = nil
+ansi = false
+positional = []
+while (arg = args.shift)
+  case arg
+  when "--template"
+    template_path = args.shift or usage_abort("--template needs a path")
+  when "--ansi"
+    ansi = true
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+    positional << arg
+  end
+end
+
+usage_abort("usage: intent-screen <intent_dir> [--template <path>] [--ansi]") unless positional.length == 1
+intent_dir = File.expand_path(positional.first)
+usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+
+store_root = File.expand_path("../..", intent_dir)
+template_path ||= File.expand_path("../templates/intent-screen.md", __dir__)
+usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+
+plain = -> { IntentScreen.render(intent_dir: intent_dir, store_root: store_root, template: File.read(template_path)) }
+
+degrade_to_plain = ENV.key?("NO_COLOR") || !$stdout.tty?
+
+$stdout.write(
+  if ansi && !degrade_to_plain
+    IntentScreenAnsi.render(intent_dir: intent_dir, store_root: store_root, color: true)
+  else
+    plain.call
+  end
+)
+exit 0

package/scripts/lib/agent_models.rb

@@ -12,13 +12,7 @@ module AgentModels
   # file basenames without the `.md` extension.
   TIER_DEFAULTS = {
     "plastic-enforcer" => "opus",
-    "plastic-brainstorming" => "opus",
-    "plastic-planner" => "opus",
-    "plastic-spec-specialist" => "sonnet",
-    "plastic-executor" => "sonnet",
-    "plastic-intent-curator" => "sonnet",
-    "plastic-future-intent-researcher" => "sonnet",
-    "plastic-intent-discovery" => "sonnet"
+    "plastic-executor" => "sonnet"
   }.freeze
 
   # The two advisor agents (intent 185 final design): plastic-advisor (the real

package/scripts/lib/arm.rb

@@ -0,0 +1,308 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require_relative "lock"
+require_relative "worktree"
+require_relative "session_ledger"
+require_relative "savepoint"
+
+# Arm - how an auto team takes an intent and gives it back (intent 307).
+#
+# Three durable facts make a delivery: the delivery lock in the intent
+# directory (who owns it), the code worktree under the project repo (where
+# the code lands), and the per-session pointer in the global store's `.tmp/`
+# (which intent this session records into; a day id means the day ledger).
+# Before 2.0 a fourth thing, a `/tmp` bridge JSON, cached all three plus a
+# stage snapshot; ruling 6 of intent 296 retired it, and this module is what
+# replaced the bridge's arm, disarm, and repair methods (removed in 2.0, intent 307).
+#
+# Pure and dependency-injected: every path and clock is an argument, every git
+# call goes through an injected runner, and the only environment read is the
+# `env:` value the caller passes to `resolve_session`. Nothing here raises for
+# a lock outcome; callers get a status and decide.
+module Arm
+  module_function
+
+  STATUSES = %i[acquired owned held stale excluded corrupt].freeze
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
+  # Deterministic, session-less key derived from the store and the intent id,
+  # for headless runs that carry no session id at all (moved from Bridge).
+  def derive_key(store, intent_id)
+    "auto-" + Digest::SHA256.hexdigest("#{store}/#{intent_id}")[0, 10]
+  end
+
+  # The session that keys a lock: the explicit id, else the env id the caller
+  # read (CLAUDE_CODE_SESSION_ID), else the derived key. Never nil.
+  def resolve_session(explicit, env: nil, store:, intent_id:)
+    return explicit.to_s.strip unless blank?(explicit)
+    return env.to_s.strip unless blank?(env)
+    derive_key(store, intent_id)
+  end
+
+  # --- derivations (no I/O beyond Dir.exist?) ---------------------------------
+
+  def intent_id_for(intent_dir)
+    File.basename(intent_dir.to_s).split("--", 2).first
+  end
+
+  def store_for(intent_dir)
+    File.dirname(File.expand_path(intent_dir))
+  end
+
+  # The home (parent of `.plastic`) an intent dir belongs to, else the given
+  # fallback. A sandboxed store never resolves to the real Dir.home.
+  def home_for(intent_dir, home: Dir.home)
+    Worktree.home_from_store(store_for(intent_dir)) || home
+  end
+
+  def global_store(home)
+    File.join(File.expand_path(home), ".plastic", "store")
+  end
+
+  # The minimal hash Worktree.provision, release, and finish consume: the
+  # intent block plus, when asked, the derived worktree block.
+  def bridge_hash(intent_dir:, home: Dir.home, with_worktree: true)
+    dir = File.expand_path(intent_dir)
+    data = {
+      "intent" => { "id" => intent_id_for(dir), "dir" => File.basename(dir), "store" => store_for(dir) },
+    }
+    data["worktree"] = worktree_block(intent_dir: dir, home: home) if with_worktree
+    data
+  end
+
+  # `{code, code_branch, provisioned}` derived from projects.yml and the
+  # intent id: the same path provision creates, `provisioned` iff it exists.
+  def worktree_block(intent_dir:, home: Dir.home)
+    dir = File.expand_path(intent_dir)
+    store = store_for(dir)
+    h = home_for(dir, home: home)
+    slug = Worktree.slug_for_store(store, home: h)
+    p = Worktree.paths(slug: slug, intent_id: intent_id_for(dir),
+                       intent_slug: Worktree.slug_from_dir(dir), home: h)
+    code = p["code"]
+    provisioned = !blank?(code) && Dir.exist?(code)
+    {
+      "code" => provisioned ? code : nil,
+      "code_branch" => provisioned ? p["code_branch"] : nil,
+      "provisioned" => provisioned,
+    }
+  end
+
+  # Owner rule 2026-08-31: does this session already have a live top-level
+  # pointer pointing SOMEWHERE ELSE (the day ledger or another intent)? A
+  # pointer already on this intent is the owner re-arming mid-delivery and
+  # stays idempotent. True means a
+  # conversation session. Reads only; rescues to false (fail open).
+  def preexisting_pointer?(session, home:)
+    path = pointer_path(session, home: home)
+    File.exist?(path) && !File.read(path).to_s.strip.empty?
+  rescue StandardError
+    false
+  end
+
+  # --- the pointer -------------------------------------------------------------
+
+
+  def pointer_path(session, home:)
+    store = global_store(home)
+    SessionLedger.pointer_path(store, SessionLedger.short_session_id(nil, session))
+  end
+
+  def read_pointer(session, home:)
+    path = pointer_path(session, home: home)
+    File.exist?(path) ? File.read(path).strip : nil
+  end
+
+  def write_pointer(session, value, home:)
+    store = global_store(home)
+    SessionLedger.ensure_tmp_root(store)
+    path = pointer_path(session, home: home)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, "#{value}\n")
+    path
+  end
+
+  # --- arm ---------------------------------------------------------------------
+
+  # Take an intent for `session`: acquire delivery.lock (stamped with the run
+  # mode and the provenance the caller knows), provision the code worktree
+  # (fail-open for a global-only or non-git intent), and point the session at
+  # the intent. Returns `{status:, lock:, worktree:, session:, pointer:}`.
+  # A held, stale, excluded, or corrupt lock returns that status with the
+  # lock data read and touches nothing.
+  def arm(intent_dir:, session:, mode: "auto", home: Dir.home, harness: nil,
+          agent: nil, model: nil, thread: nil, now: Time.now, runner: Worktree::ShellRunner.new,
+          host: Socket.gethostname, allow_inline: false)
+    raise ArgumentError, "mode must be auto or guided" unless %w[auto guided].include?(mode.to_s)
+    dir = File.expand_path(intent_dir)
+    key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
+    h = home_for(dir, home: home)
+
+    # Owner rule 2026-08-31: the main session never delivers an intent inline.
+    # A session that already carries a top-level session pointer is a
+    # conversation session (SessionStart wrote it at boot); arming there is
+    # inline delivery and is refused BEFORE any lock is taken. A dispatched or
+    # headless session has no pre-existing pointer and arms freely.
+    # --allow-inline is the explicit owner override. Fail open on read errors:
+    # a broken pointer file must never block a legitimate delivery.
+    if !allow_inline && preexisting_pointer?(key, home: h) &&
+       read_pointer(key, home: h).to_s.strip != intent_id_for(dir)
+      return { status: :inline_refused, lock: nil, worktree: nil, session: key, pointer: nil }
+    end
+
+    status, lock = Lock.acquire(dir, session: key, host: host, now: now,
+                                harness: harness, agent: agent, model: model,
+                                thread: thread, run_mode: mode.to_s)
+    unless %i[acquired owned].include?(status)
+      return { status: status, lock: lock, worktree: nil, session: key, pointer: nil }
+    end
+
+    data = bridge_hash(intent_dir: dir, home: h, with_worktree: false)
+    begin
+      Worktree.provision(data, home: h, runner: runner)
+    rescue StandardError => e
+      warn "plastic: worktree provision raised, continuing unprovisioned: #{e.message}"
+    end
+
+    # The pointer is what the capture and record hooks read; they key on the
+    # harness's real session id, so a derived key gets no pointer (nothing would
+    # ever read it). A pointer failure warns and never undoes an acquired lock.
+    pointer = nil
+    unless key == derive_key(store_for(dir), intent_id_for(dir))
+      begin
+        pointer = write_pointer(key, intent_id_for(dir), home: h)
+      rescue StandardError => e
+        warn "plastic: session pointer not written (#{e.message}); the lock is held regardless"
+      end
+    end
+    { status: status, lock: lock, worktree: worktree_block(intent_dir: dir, home: h),
+      session: key, pointer: pointer }
+  end
+
+  # --- disarm ------------------------------------------------------------------
+
+  # Give the intent back: remove the worktree (when `remove`), release the
+  # lock as its recorded owner (falling back to `session`), and reset the
+  # session pointer to today's day id when it named this intent. Returns
+  # the lock release status (:released, :none, :not_owner, or :raised).
+  def disarm(intent_dir:, session:, home: Dir.home, runner: Worktree::ShellRunner.new,
+             remove: true, now: Time.now)
+    dir = File.expand_path(intent_dir)
+    h = home_for(dir, home: home)
+    key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
+
+    begin
+      Worktree.release(bridge_hash(intent_dir: dir, home: h), home: h, runner: runner, remove: remove)
+    rescue StandardError => e
+      warn "plastic: worktree release raised, continuing: #{e.message}"
+    end
+
+    lock = Lock.read(dir)
+    owner = lock && !blank?(lock["owner_session"]) ? lock["owner_session"] : key
+    release_status = begin
+      Lock.release(dir, session: owner)
+    rescue StandardError => e
+      warn "plastic: delivery lock release raised for #{dir}, continuing: #{e.message}"
+      :raised
+    end
+
+    begin
+      reset_pointer(key, intent_id_for(dir), home: h, now: now)
+    rescue StandardError => e
+      warn "plastic: session pointer not reset (#{e.message})"
+    end
+    release_status
+  end
+
+  # Point the session back at the day ledger, but only when it names `intent_id`.
+  def reset_pointer(session, intent_id, home:, now: Time.now)
+    current = read_pointer(session, home: home)
+    return false unless current == intent_id.to_s
+    write_pointer(session, SessionLedger.day_id(now), home: home)
+    true
+  end
+
+  # --- repair ------------------------------------------------------------------
+
+  # One idempotent repair (the lock half of the bridge's repair, removed in 2.0):
+  # remove a corrupt lock, back off from a fresh foreign lock (`held`), report
+  # a stale foreign lock (`stale`) for the explicit reclaim verb, keep and
+  # enrich an own lock, heartbeat a delegated one, acquire when none, and
+  # provision the worktree so the repaired intent has its checkout.
+  def repair(intent_dir:, session:, home: Dir.home, now: Time.now, harness: nil,
+             agent: nil, model: nil, thread: nil, run_mode: nil, hint_harness: nil,
+             runner: Worktree::ShellRunner.new)
+    dir = File.expand_path(intent_dir)
+    h = home_for(dir, home: home)
+    key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
+    actions = []
+
+    if Lock.corrupt?(dir)
+      File.delete(Lock.path(dir))
+      actions << "removed corrupt delivery.lock"
+    end
+
+    lock = Lock.read(dir)
+    if lock && !Lock.authorized?(lock, key)
+      if Lock.fresh?(dir, now: now)
+        return { "status" => "held", "owner" => lock["owner_session"],
+                 "actions" => actions, "session" => key }
+      end
+      return { "status" => "stale", "owner" => lock["owner_session"],
+               "actions" => actions, "session" => key,
+               "hint" => "run #{Lock.skill_ref('plastic-doctor', harness: hint_harness || harness)} " \
+                         "reclaim the lock to take over with an audit" }
+    end
+
+    mode = blank?(run_mode) ? (lock && lock["run_mode"]) : run_mode.to_s
+    if lock
+      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" => 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.to_s ? "owner" : "delegate"
+      actions << "lock kept (#{role})"
+    else
+      status, lock_data = Lock.acquire(dir, session: key, now: now, harness: harness,
+                                       agent: agent, model: model, thread: thread,
+                                       run_mode: mode)
+      actions << "lock #{status}"
+    end
+
+    begin
+      Worktree.provision(bridge_hash(intent_dir: dir, home: h, with_worktree: false), home: h, runner: runner)
+    rescue StandardError => e
+      warn "plastic: worktree provision raised during repair, continuing unprovisioned: #{e.message}"
+    end
+    actions << "worktree #{worktree_block(intent_dir: dir, home: h)['provisioned'] ? 'present' : 'absent'}"
+    actions << "stage #{Savepoint.derive_stage(dir)}"
+
+    { "status" => "repaired", "actions" => actions, "lock" => lock_data, "session" => key }
+  end
+
+  # The intent directory this session's pointer names, searched in the given
+  # stores in order; nil when the pointer is absent, empty, or a day id.
+  def intent_dir_from_pointer(session, home:, stores:)
+    current = read_pointer(session, home: home)
+    return nil if blank?(current) || SessionLedger.valid_day_id?(current)
+    stores.each do |store|
+      match = Dir.glob(File.join(store, "#{current}--*")).find { |p| File.directory?(p) }
+      return match if match
+    end
+    nil
+  end
+end