@zalom/plastic 1.14.1 → 2.0.0-alpha.10

package/scripts/lib/intent_screen_ansi.rb

@@ -0,0 +1,262 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_screen"
+
+# IntentScreenAnsi (intent 316a, O2) - renders one intent screen with raw
+# truecolor ANSI escapes, productionizing 318's mockup--render.rb. Standard
+# library only. Calls the SAME public IntentScreen.* field methods
+# scripts/intent-screen calls (store_fields, index_fields, savepoint_fields,
+# checklist_items, progress_fields, next_fields, insight_fields,
+# items_present?, fallback_name, step_text) and re-derives nothing, so every
+# field the ANSI block prints is the identical value the plain screen prints
+# (D3), just carried through a different layout.
+#
+# `color:` is a constructor/call argument, never an environment read (D18):
+# the plain path (`color: false`) is one call away and testable without
+# touching NO_COLOR or a TTY. No ENV, no Dir.pwd, no Dir.home.
+#
+# Harness-agnostic core: no harness assumption lives here. `markdown_safe:`
+# (intent 316a1, D3/D5) is the one choice a caller supplies rather than a
+# choice this module makes for itself: a display surface that passes raw
+# ANSI through untouched should not inherit a concession it never needed.
+# See docs/reference/harness-adapters.md for which caller asks for it and
+# why.
+module IntentScreenAnsi
+  ESC = "\e"
+  RESET = "#{ESC}[0m".freeze
+  BOLD = "#{ESC}[1m".freeze
+  TEAL = "#{ESC}[38;2;45;212;191m".freeze
+  AMBER = "#{ESC}[38;2;245;158;11m".freeze
+  GRAPHITE_BG = "#{ESC}[48;2;31;41;55m".freeze
+  MIDGREY = "#{ESC}[38;2;148;163;184m".freeze
+  NEARWHITE = "#{ESC}[38;2;243;244;246m".freeze
+
+  BAR_CELLS = 24
+  EIGHTHS = [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"].freeze
+
+  # Intent 317a1 (D14): the approved design is a 115-column layout, measured
+  # from design--terminal-output.html:52-58 with its tags stripped.
+  DEFAULT_WIDTH = 115
+
+  ELLIPSIS = "…"
+
+  # Intent 317a1 (D9-D11, D15): the three-column field table's geometry.
+  # ANSI_RE strips escapes so padding measures what the terminal actually
+  # draws (D10); VALUE_COL_MAX is the design's own value-column figure and
+  # the owner's "50 chars" (mockup--report-screen.md:74); NOTE_FLOOR is the
+  # minimum note length that earns the own-line fallback when the note alone
+  # (not the value) is what overflows the same-line budget.
+  ANSI_RE = /\e\[[0-9;]*m/.freeze
+  VALUE_COL_MAX = 50
+  NOTE_FLOOR = 24
+
+  def self.visible_width(text)
+    text.to_s.gsub(ANSI_RE, "").length
+  end
+
+  def self.render(intent_dir:, store_root:, color: true, width: DEFAULT_WIDTH, markdown_safe: false)
+    base = File.basename(intent_dir)
+    id = base.split("--", 2).first
+    intent_text = File.read(File.join(intent_dir, "#{base}.md"))
+
+    fields = {}
+    fields.merge!(IntentScreen.store_fields(store_root))
+    status, title = IntentScreen.index_fields(store_root, id)
+    fields["status"] = status
+    fields["status.note"] = status == "unlisted" ? "no INDEX.md line names this id" : "listed under ## #{status} in INDEX.md"
+    fields["id"] = id
+    fields["name"] = title || IntentScreen.fallback_name(intent_text)
+    fields.merge!(IntentScreen.savepoint_fields(intent_dir, intent_text))
+    items = IntentScreen.checklist_items(intent_dir)
+    fields.merge!(IntentScreen.progress_fields(items))
+    fields.merge!(IntentScreen.next_fields(items, status, checklist_present: IntentScreen.items_present?(intent_dir), escape_pipes: false))
+    fields.merge!(IntentScreen.insight_fields(intent_text, escape_pipes: false))
+    fields.transform_values! { |v| markdown_safe ? clean(v) : v }
+
+    done_n = fields["progress.done"].to_i
+    total_n = fields["progress.total"].to_i
+
+    out = +""
+    out << fit("▶ #{fields['id']} · #{fields['name']}", width) { |t| styled(t, color, BOLD, NEARWHITE) }
+    out << "\n\n"
+
+    # The 4th column marks a row whose value is already a finished, pre-fit
+    # string (the Progress bar, built above from styled glyphs plus a count)
+    # rather than raw field text still needing `fit_plain`. Naming that
+    # explicitly here reads better than testing the value for a leading ESC
+    # byte further down, which is really just asking "is this the Progress
+    # row?" through a type check.
+    field_rows = [
+      ["Store", fields["store"], fields["store.note"], false],
+      ["Status", fields["status"], fields["status.note"], false],
+      ["Stage", fields["stage"], fields["stage.note"], false],
+      ["Savepoint", fields["savepoint"], fields["savepoint.note"], false],
+      ["Progress", "#{render_bar(done_n, total_n, color)}  #{done_n} / #{total_n}", fields["progress.note"], true],
+      ["Next", fields["next"], fields["next.note"], false],
+      ["Insight", fields["insight"], fields["insight.note"], false],
+    ]
+    key_width = field_rows.map { |k, _, _, _| k.length }.max
+
+    out << field_table_lines(field_rows, width: width, color: color, key_width: key_width)
+
+    out << "\n"
+    out << fit("Steps", width) { |t| styled(t, color, BOLD, NEARWHITE) }
+    out << "\n\n"
+
+    if items.empty?
+      out << "  no steps yet\n"
+    else
+      # Padded to the widest label (matrix B2): at 10+ steps "S10" is one
+      # column wider than "S1..S9", and without padding every badge past S9
+      # drifts out of column with the rows above it.
+      label_width = "S#{items.size}".length
+      items.each_with_index do |item, i|
+        num = "S#{i + 1}".ljust(label_width)
+        badge = status_cell(item[:done], color)
+        prefix_plain = "  #{num}  [ #{item[:done] ? 'done' : 'open'} ]  "
+        text_budget = [width - prefix_plain.length, 0].max
+        step = IntentScreen.step_text(item[:text])
+        text = fit_plain(markdown_safe ? clean(step) : step, text_budget)
+        out << "  #{num}  [#{badge}]  #{text}\n"
+      end
+    end
+
+    out
+  end
+
+  # --- shared field-table geometry (D9-D12, D14, D15) ------------------------
+
+  # The field table's basis, cap, budget arithmetic, both fallbacks, and the
+  # right-strip, shared by `render` above and `ScreenPaint.paint_table`'s
+  # `**Key**` branch, so the two renderers can never drift apart (D12) - the
+  # duplication this replaced was character-for-character identical apart
+  # from the module prefix. `rows` is `[key, value, note]`, or `[key, value,
+  # note, true]` when `value` is already a finished, pre-fit string (the
+  # Progress bar) rather than raw text still needing `fit_plain`.
+  #
+  # Notes become a third column, padded to the widest RENDERED noted value
+  # (capped at VALUE_COL_MAX, D15) so every note starts at one raw-text
+  # position; a row whose value or note will not fit drops to the
+  # note-on-its-own-line form instead of squeezing anything invisibly. When
+  # the same-line budget has already collapsed to zero or less, the note
+  # falls straight to its own line rather than being fed to `fit` and
+  # silently returning "" - the note must be cut with a visible ellipsis or
+  # kept whole, never dropped outright (317a1 post-exec review, finding 4).
+  def self.field_table_lines(rows, width:, color:, key_width:)
+    prefix_width = key_width + 4 # "  " + key.ljust + "  "
+
+    rendered_rows = rows.map do |key, value, note, prebuilt|
+      value_budget = [width - prefix_width, 0].max
+      value_text = prebuilt ? value : fit_plain(value.to_s, value_budget)
+      [key.to_s, value_text, note.to_s]
+    end
+
+    noted_widths = rendered_rows.filter_map { |_, value_text, note| visible_width(value_text) unless note.empty? }
+    value_col = [noted_widths.max.to_i, VALUE_COL_MAX].min
+    note_budget = width - prefix_width - value_col - 2
+
+    out = +""
+    rendered_rows.each do |key, value_text, note|
+      row = "  #{styled(key.ljust(key_width), color, BOLD)}  #{value_text}"
+      if note.empty?
+        out << row.rstrip << "\n"
+        next
+      end
+
+      value_fits = visible_width(value_text) <= value_col
+      note_width = visible_width(note)
+      note_overflows = note_width > note_budget
+      note_fits = !note_overflows || (note_budget.positive? && note_width <= NOTE_FLOOR)
+      if value_fits && note_fits
+        pad = value_col - visible_width(value_text)
+        out << row << (" " * pad) << "  " << fit(note, note_budget) { |t| styled(t, color, MIDGREY) } << "\n"
+      else
+        out << row.rstrip << "\n"
+        own_budget = [width - prefix_width, 0].max
+        out << (" " * prefix_width) << fit(note, own_budget) { |t| styled(t, color, MIDGREY) } << "\n"
+      end
+    end
+    out
+  end
+
+  # --- markdown-noise stripping, adapter-optional (intent 316a1, D3/D5) ------
+  #
+  # Not every display surface passes text through a Markdown renderer, so
+  # stripping is not this module's call to make (see `markdown_safe:` on
+  # `render` above; the justification for WHY a caller would ever ask for
+  # this lives with that caller, in scripts/lib/message_display.rb). When
+  # asked, strips backticks and neutralises `*`/`_` runs from a value.
+  # Single underscores are left alone: they are common inside ordinary words
+  # (`intent_screen.rb`) and GFM does not treat an intraword underscore as
+  # emphasis; only a run of 2+ (the bold marker `__`) is markdown-active.
+  def self.clean(text)
+    text.to_s.delete("`*").gsub(/_{2,}/, "")
+  end
+
+  # --- width cap (D15, matrix 18) --------------------------------------------
+
+  # Truncates `text` to `max` visible columns with a trailing ellipsis when
+  # cut, then yields the truncated plain text to the block for coloring.
+  # Coloring never adds visible width. The cap itself is harness-neutral: a
+  # fixed width, not a re-flow, is what lets a column layout survive whatever
+  # display eventually shows it — no display's own wrapping is assumed here.
+  def self.fit(text, max)
+    plain = fit_plain(text, max)
+    block_given? ? yield(plain) : plain
+  end
+
+  def self.fit_plain(text, max)
+    return "" if max <= 0
+    return text if text.length <= max
+    return ELLIPSIS[0, max] if max <= 1
+
+    "#{text[0, max - 1]}#{ELLIPSIS}"
+  end
+
+  # --- palette ----------------------------------------------------------------
+
+  def self.styled(text, color, *codes)
+    return text unless color
+
+    "#{codes.join}#{text}#{RESET}"
+  end
+
+  def self.status_cell(done, color)
+    label = done ? " done " : " open "
+    return label unless color
+
+    hue = done ? TEAL : AMBER
+    "#{hue}#{BOLD}#{label}#{RESET}"
+  end
+
+  # `.dup` matters, not just style (318's own note, carried forward): these
+  # constants are built via string interpolation, which frozen_string_literal
+  # does NOT freeze automatically — only static literals get that. `.freeze`
+  # above makes them immutable, but `bar << ...` below still needs its OWN
+  # mutable copy or it would raise (or, without the freeze, silently corrupt
+  # the shared constant for every later call in the same process — matrix 16).
+  def self.render_bar(done, total, color)
+    ratio = total.zero? ? 0.0 : done.to_f / total
+
+    unless color
+      on = total.zero? ? 0 : (done * BAR_CELLS) / total
+      return ("#" * on) + ("." * (BAR_CELLS - on))
+    end
+
+    units = (ratio * BAR_CELLS * 8).round.clamp(0, BAR_CELLS * 8)
+    full, rem = units.divmod(8)
+    full = [full, BAR_CELLS].min
+
+    bar = TEAL.dup
+    bar << ("█" * full)
+    if full < BAR_CELLS && rem.positive?
+      bar << EIGHTHS[rem]
+      full += 1
+    end
+    track = BAR_CELLS - full
+    bar << GRAPHITE_BG << (" " * track) if track.positive?
+    bar << RESET
+    bar
+  end
+end

package/scripts/lib/lock.rb

@@ -49,11 +49,11 @@ module Lock
   DELEGATE_ACTIVITY_LIMIT = 20
   DELEGATE_STATUSES = %w[active finished failed].freeze
 
-  # Lease TTL. Heartbeats fire from the write-path hooks (PostToolUse
-  # gate-check and the lock-gate allow path), so a delivering session
-  # refreshes constantly; 30 minutes tolerates long read-only stretches
-  # without opening a takeover window mid-delivery. Reclaim is explicit
-  # either way (takeover), so the TTL only bounds WHEN takeover is allowed.
+  # Lease TTL. Heartbeats fire from the PostToolUse record hook on every write
+  # inside the intent dir (intent 302), so a delivering session refreshes
+  # constantly; 30 minutes tolerates long read-only stretches without opening
+  # a takeover window mid-delivery. Reclaim is explicit 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
@@ -122,7 +122,7 @@ module Lock
     Array(data["delegates"]).map(&:to_s).include?(session.to_s)
   end
 
-  # The one question gates ask: does session hold this intent's lock?
+  # The one question the write path asks: does session hold this intent's lock?
   # Owner/delegate on an EXISTING lock counts even when stale (a stale lock is
   # still theirs until an explicit takeover replaces it); freshness only
   # guards AGAINST other sessions.
@@ -676,24 +676,4 @@ module Claim
     end
   end
 
-  # Second, independent write gate at the artifact grain (intent 111 D7). Returns a
-  # deny reason String to BLOCK, or nil to ALLOW. Composes UNDER the delivery-lock
-  # gate: only reached after the session already holds the intent's delivery lock.
-  # ENGAGES only when a claim file exists (dormant otherwise, so single-owner flows
-  # and the existing suite stay green, AC7). Fails open on stale/corrupt via
-  # fail_open?, the named contract.
-  def claim_gate_reason(intent_dir, artifact, session:, ttl: Lock::TTL_SECONDS, now: Time.now,
-                        harness: :claude)
-    return nil if Lock.blank?(artifact)
-    return nil unless File.exist?(path(intent_dir, artifact))   # dormant: no claim
-    return nil if holds_claim?(intent_dir, artifact, session: session)  # you hold it
-    return nil if fail_open?(intent_dir, artifact, ttl: ttl, now: now)  # stale/corrupt: yield
-    data = read(intent_dir, artifact)
-    holder = data && data["owner_session"]
-    since = data && data["acquired_at"]
-    "artifact #{artifact} is claimed by #{holder} since #{since}; another writer holds " \
-      "it. Back off or run #{Lock.skill_ref('plastic-doctor', harness: harness)} check the " \
-      "lock status. If you are a distinct delegate, the owner must register you: " \
-      "plastic-lock delegate --intent-dir #{intent_dir} --session <your-session-id>"
-  end
 end

package/scripts/lib/message_display.rb

@@ -0,0 +1,290 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "screen_paint"
+
+# MessageDisplay (intent 316a, O4/O5, round 3 concurrency fix) - the Claude
+# Code MessageDisplay hook handler. One process per streamed chunk of every
+# assistant message (D11), so it must be cheap and decide fast. Pure: every
+# dependency (tmp_root, plastic_home, color, now, wait_ms, poll_ms, sleeper)
+# is a constructor argument, never an ENV read, a Dir.pwd/Dir.home read, or
+# the real Time.now/Kernel#sleep — the thin CLI (scripts/hook-message-display)
+# is the one place allowed to read any of those.
+#
+# Claude adapter: Claude Code only; the core is harness-agnostic. (intent
+# 316a1, D3 supersedes 316a's D6.) This is the sole caller that asks
+# IntentScreenAnsi.render for `markdown_safe: true` (scripts/lib/
+# intent_screen_ansi.rb) — see `finalize` below for why.
+#
+# A live run under a real pty (round 3) found that Claude Code fires the
+# per-chunk hook processes CONCURRENTLY, not strictly in order. Chunk 0 is
+# the one that recognizes the screen and creates the buffer (D13), and it can
+# lose the race to chunks with a higher index: they would find no buffer yet
+# and pass their raw Markdown straight through, producing a half plain /
+# half styled screen. This class now survives that:
+#
+#   - One file per chunk (index-named), written atomically (temp name in the
+#     same directory, then File.rename), so reassembly never depends on
+#     arrival order — only on the index each chunk already carries.
+#   - A decision file written BEFORE anything slow: chunk 0 writes SCREEN
+#     (the resolved intent dir + store root) the moment it engages, or
+#     NOSCREEN the moment it does not, so later chunks can decide without
+#     redoing any of chunk 0's work.
+#   - A later chunk asks a cheap, local question before ever waiting: could
+#     this delta plausibly be part of a screen (leading "|", "**Steps**", or
+#     blank)? An ordinary prose chunk arriving before SCREEN/NOSCREEN exists
+#     passes through at once, at zero cost. A chunk shaped like part of a
+#     screen polls for the decision, bounded (wait_ms/poll_ms), then fails
+#     open. The final chunk always waits for the decision, whatever its own
+#     shape, since it is the one that must not race — and it additionally
+#     waits (same budget) for every earlier chunk file to exist before it
+#     splices, returning whatever it does have rather than nothing when the
+#     budget runs out.
+#
+# Protocol (D13, preserved): chunk 0 still decides, once, before anything is
+# buffered or blanked. D10 (any failure while finalizing returns the
+# buffered original, never nil, never "") and D12 (color: false never
+# buffers or blanks anything) are unchanged.
+class MessageDisplay
+  # 317a (A4): engagement is grammar, not identity - any screen-family
+  # opener engages, with NO intent-id resolution (the roster and delay
+  # screens have none to resolve). ScreenPaint owns the full grammar.
+  ENGAGE_RE = /\A(?:##? )?[▶✔] /.freeze
+  BUFFER_DIR_NAME = "plastic-message-display"
+  BUFFER_MAX_AGE_SECONDS = 3600
+  SCREEN_FILE = "SCREEN"
+  NOSCREEN_FILE = "NOSCREEN"
+
+  def initialize(tmp_root:, plastic_home:, color:, now:, wait_ms: 300, poll_ms: 20,
+                 sleeper: ->(seconds) { sleep(seconds) })
+    @tmp_root = tmp_root
+    @plastic_home = plastic_home
+    @color = color
+    @now = now
+    @wait_ms = wait_ms
+    @poll_ms = poll_ms
+    @sleeper = sleeper
+  end
+
+  def handle(payload)
+    return nil unless @color
+    return nil unless payload.is_a?(Hash)
+
+    prune_old_buffers
+
+    message_id = payload["message_id"].to_s
+    session_id = payload["session_id"].to_s
+    delta = payload["delta"].to_s
+    final = payload["final"] == true
+    index = payload["index"]
+    cwd = payload["cwd"].to_s
+
+    return nil if message_id.empty? || session_id.empty?
+
+    dir = self.class.buffer_path(tmp_root: @tmp_root, session_id: session_id, message_id: message_id)
+
+    if index == 0
+      handle_chunk_zero(dir, delta, cwd, final)
+    else
+      handle_later_chunk(dir, index, delta, final)
+    end
+  end
+
+  # The message directory both this class and the bash launcher (hooks/
+  # message-display) must agree on byte for byte (matrix 40): the launcher
+  # checks this exact path's existence to decide whether chunk > 0 of an
+  # engaged message gets handed to Ruby at all.
+  def self.buffer_path(tmp_root:, session_id:, message_id:)
+    File.join(tmp_root, BUFFER_DIR_NAME, session_id, message_id)
+  end
+
+  def self.chunk_path(tmp_root:, session_id:, message_id:, index:)
+    File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), index.to_s)
+  end
+
+  def self.screen_path(tmp_root:, session_id:, message_id:)
+    File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), SCREEN_FILE)
+  end
+
+  def self.noscreen_path(tmp_root:, session_id:, message_id:)
+    File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), NOSCREEN_FILE)
+  end
+
+  private
+
+  # Chunk 0 decides, synchronously, before anything else touches this
+  # message: recognize the marker (after leading whitespace only) AND
+  # resolve the id, both before anything is buffered or blanked (F4). Either
+  # failure writes NOSCREEN so every later chunk can decide instantly rather
+  # than waiting out its own budget for a decision that will never arrive.
+  def handle_chunk_zero(dir, delta, _cwd, final)
+    stripped = delta.sub(/\A[ \t]+/, "")
+    unless ENGAGE_RE.match?(stripped)
+      write_noscreen(dir)
+      return nil
+    end
+
+    write_screen(dir)
+    write_chunk(dir, 0, delta)
+    final ? finalize_final(dir, 0) : ""
+  end
+
+  # A later chunk (index > 0) never redoes chunk 0's work: it only asks
+  # whether a decision already exists, waiting for one (bounded) when it
+  # does not and the chunk looks like it could matter. The final chunk
+  # always waits for the decision regardless of its own shape.
+  def handle_later_chunk(dir, index, delta, final)
+    decision = wait_for_decision(dir, gate_delta: final ? nil : delta)
+
+    return nil unless decision == :screen
+
+    write_chunk(dir, index, delta)
+    final ? finalize_final(dir, index) : ""
+  end
+
+  # Checks for an existing decision first (free) and only pays the cheap
+  # shape test, then the bounded poll, when neither SCREEN nor NOSCREEN is
+  # there yet. `gate_delta: nil` (the final chunk) skips the shape test
+  # entirely and always polls for the decision.
+  def wait_for_decision(dir, gate_delta:)
+    decision = read_decision_now(dir)
+    return decision if decision
+
+    return :timeout if gate_delta && !maybe_screen?(gate_delta)
+
+    max_polls_for_budget.times do
+      @sleeper.call(@poll_ms / 1000.0)
+      decision = read_decision_now(dir)
+      return decision if decision
+    end
+
+    :timeout
+  end
+
+  def read_decision_now(dir)
+    return :screen if File.exist?(File.join(dir, SCREEN_FILE))
+    return :noscreen if File.exist?(File.join(dir, NOSCREEN_FILE))
+
+    nil
+  end
+
+  # Cheap, local, no file I/O: could this chunk's own delta plausibly be
+  # part of an intent screen (ignoring leading whitespace)? Every chunk of
+  # every ordinary prose message answers no, at zero cost.
+  def maybe_screen?(delta)
+    stripped = delta.lstrip
+    stripped.empty? || stripped.start_with?("|") || stripped.start_with?("**")
+  end
+
+  # The final chunk additionally waits (same budget) for every earlier chunk
+  # file to exist before it reassembles and splices. On timeout it proceeds
+  # anyway with whatever is there (matrix, lead's guard): never nil, never
+  # swallowed.
+  def finalize_final(dir, index)
+    wait_for_chunk_files(dir, index)
+
+    buffered = nil
+    begin
+      buffered = read_buffered_chunks(dir, index)
+      finalize(buffered, nil)
+    rescue StandardError
+      buffered
+    ensure
+      FileUtils.rm_rf(dir)
+    end
+  end
+
+  def wait_for_chunk_files(dir, index)
+    return if index <= 0
+
+    needed = (0...index).map(&:to_s)
+    max_polls_for_budget.times do
+      return if needed.all? { |n| File.exist?(File.join(dir, n)) }
+
+      @sleeper.call(@poll_ms / 1000.0)
+    end
+  end
+
+  def max_polls_for_budget
+    return 0 unless @poll_ms.to_f.positive?
+
+    (@wait_ms / @poll_ms.to_f).ceil
+  end
+
+  # Whatever chunk files exist, in index order, concatenated -- gaps (a
+  # chunk that never arrived, or arrived too late) are skipped rather than
+  # blocking reassembly (lead's guard: never return nothing).
+  def read_buffered_chunks(dir, index)
+    (0..index).filter_map do |i|
+      path = File.join(dir, i.to_s)
+      File.exist?(path) ? File.read(path) : nil
+    end.join
+  end
+
+  # 317a (D1/B10): paint what was printed. The buffered message's screen
+  # region - located and bounded by ScreenPaint's own grammar - is re-laid in
+  # the ANSI vocabulary; prose before and after survives verbatim. A region
+  # the painter cannot parse returns the buffered original (A3: chunks were
+  # already blanked, so nil here would truncate the message to its final
+  # delta; nil is only for the never-engaged path in handle).
+  #
+  # markdown_safe: true (intent 316a1, D5) - Claude Code still Markdown-
+  # processes displayContent even inside a raw ANSI block, so the Claude
+  # adapter asks the harness-agnostic core to strip markdown noise. A harness
+  # whose display surface passes raw ANSI through untouched would ask for
+  # false instead.
+  def finalize(buffered, _decision)
+    lines = buffered.lines
+    start = lines.index { |l| ScreenPaint.classify(l) == :opener }
+    return buffered unless start
+
+    stop = ScreenPaint.region_end(lines, start)
+    painted = ScreenPaint.paint(lines[start...stop].join, color: true, markdown_safe: true)
+    return buffered unless painted
+
+    suffix = lines[stop..].to_a.join.sub(/\A\n+/, "")
+    out = +"#{lines[0...start].join}#{painted.rstrip}\n"
+    out << "\n#{suffix}" unless suffix.empty?
+    out
+  end
+
+  def write_chunk(dir, index, delta)
+    atomic_write(File.join(dir, index.to_s), delta)
+  end
+
+  # IntentScreen/IntentScreenAnsi's store_root: is the TIER root (what HOLDS
+  # store/ — e.g. .../projects/<slug> or plastic_home itself), never the
+  # store/ directory itself; resolve_intent_dir's `root:` is already that.
+  def write_screen(dir)
+    atomic_write(File.join(dir, SCREEN_FILE), "")
+  end
+
+  def write_noscreen(dir)
+    atomic_write(File.join(dir, NOSCREEN_FILE), "")
+  end
+
+  def atomic_write(path, content)
+    FileUtils.mkdir_p(File.dirname(path))
+    tmp_path = "#{path}.tmp#{Process.pid}-#{rand(1_000_000)}"
+    File.write(tmp_path, content)
+    File.rename(tmp_path, path)
+  end
+
+
+
+  def prune_old_buffers
+    root = File.join(@tmp_root, BUFFER_DIR_NAME)
+    return unless File.directory?(root)
+
+    Dir.children(root).each do |session_dir|
+      full = File.join(root, session_dir)
+      next unless File.directory?(full)
+
+      age = @now.to_i - File.mtime(full).to_i
+      FileUtils.rm_rf(full) if age > BUFFER_MAX_AGE_SECONDS
+    end
+  rescue StandardError
+    nil
+  end
+end

package/scripts/lib/outcome_guard.rb

@@ -1,14 +1,16 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-require_relative "bridge"
+require_relative "savepoint"
 require_relative "intent_validator"
 
 # OutcomeGuard - the single definition of "is outcome.md real and disposition-matched for
 # THIS close" (intent 222). Extracted verbatim from scripts/end-intent's own
-# outcome_guard_reason (intent 161/188) so end-intent's existing exit-2 path and doctor's new
-# per-intent check (intent_lifecycle_artifacts) can never independently drift on what counts
-# as a valid outcome.md. Pure, read-only: authors nothing regardless of outcome.
+# outcome_guard_reason (intent 161/188) so its two callers, doctor's per-intent check
+# (intent_lifecycle_artifacts) and end-intent's post-backfill self-check, can never drift on
+# what counts as a valid outcome.md. Since intent 308 nothing blocks on it: end-intent
+# backfills a missing or placeholder outcome.md first, prints a non-nil reason, and proceeds.
+# Pure, read-only: authors nothing regardless of outcome.
 module OutcomeGuard
   module_function
 
@@ -23,7 +25,7 @@ module OutcomeGuard
 
     content = File.read(path)
     first_line = content.each_line.first.to_s.chomp
-    if first_line == Bridge::PLACEHOLDER_SENTINEL
+    if first_line == Savepoint::PLACEHOLDER_SENTINEL
       return "outcome.md is still the scaffold placeholder (first line is the sentinel)"
     end
 

package/scripts/lib/project_validator.rb

@@ -24,6 +24,15 @@ require "yaml"
 module ProjectValidator
   module_function
 
+  # The two enumerated flow: knobs (intent 300, spec D2). Kept as a plain
+  # literal here rather than a require on SessionGit: this validator only
+  # reports a bad value in `errors` (project.yml is still "accepted", spec
+  # D2's matrix row), it never blocks spawn completeness, since a bad value
+  # degrades gracefully at commit time (SessionGit falls back with a Note)
+  # rather than blocking the spawn.
+  FLOW_MODES = %w[direct pull_request].freeze
+  FLOW_WORKSPACES = %w[checkout worktree].freeze
+
   def validate(slug, plastic_home: File.join(Dir.home, ".plastic"))
     missing = []
     errors = []
@@ -53,7 +62,9 @@ module ProjectValidator
       rescue StandardError
         nil
       end
-      unless parsed.is_a?(Hash)
+      if parsed.is_a?(Hash)
+        validate_flow_block(parsed, errors)
+      else
         missing << "project.yml (valid YAML)"
         errors << "project.yml exists at #{project_yml_path} but does not parse as YAML"
       end
@@ -88,6 +99,24 @@ module ProjectValidator
     { ok: missing.empty?, missing: missing, errors: errors }
   end
 
+  # Non-blocking: an unknown `mode` or `workspace` value in project.yml's
+  # `flow:` block, if present, is reported in `errors` but never added to
+  # `missing`, so it never flips `ok`.
+  def validate_flow_block(parsed, errors)
+    flow = parsed["flow"]
+    return unless flow.is_a?(Hash)
+
+    validate_flow_knob(flow, "mode", FLOW_MODES, errors)
+    validate_flow_knob(flow, "workspace", FLOW_WORKSPACES, errors)
+  end
+
+  def validate_flow_knob(flow, key, allowed, errors)
+    value = flow[key]
+    return if value.nil? || allowed.include?(value.to_s)
+
+    errors << "project.yml flow.#{key} is #{value.inspect}, must be one of #{allowed.join(", ")}"
+  end
+
   # Invariant 1: registered in projects.yml with a 'path'. Returns the
   # project's entry Hash, or nil when unregistered or the entry has no path.
   def registration_for(slug, plastic_home)