@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.21

package/scripts/hook-message-display

@@ -0,0 +1,81 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# hook-message-display (intent 316a, O4): the MessageDisplay hook CLI. Reads
+# the harness's per-chunk JSON payload from stdin, hands it to MessageDisplay
+# (the pure handler class), and prints the hookSpecificOutput envelope when a
+# String comes back. Always exits 0, whatever happens — a raised exception
+# here must never surface as a non-zero exit or stray stderr on an ordinary
+# chunk of an ordinary message (matrix 31).
+#
+# This script is the one place in the O4 stack allowed to read ENV, the
+# clock, or Dir.tmpdir: MessageDisplay itself takes tmp_root/plastic_home/
+# color/now as constructor arguments and touches none of them directly.
+#
+# Claude adapter: Claude Code only; the core is harness-agnostic.
+
+# 317a (B1): the requires sit inside their own rescue - a missing or broken
+# lib file must never surface as a non-zero exit or stderr on a chunk of an
+# ordinary message (LoadError is a ScriptError, outside StandardError).
+begin
+  require "json"
+  require "time"
+  require "tmpdir"
+  require "yaml"
+  require_relative "lib/message_display"
+rescue ScriptError, StandardError
+  exit 0
+end
+
+def color_enabled?(plastic_home)
+  return false unless ENV["NO_COLOR"].to_s.empty?
+
+  cfg_path = File.join(plastic_home, "config.yml")
+  return true unless File.exist?(cfg_path)
+
+  cfg = YAML.safe_load(File.read(cfg_path))
+  display = cfg.is_a?(Hash) ? cfg["display"] : nil
+  return true unless display.is_a?(Hash)
+
+  display.fetch("ansi_screen", true) != false
+rescue StandardError
+  true
+end
+
+begin
+  raw = $stdin.tty? ? "" : $stdin.read
+  payload = raw.to_s.strip.empty? ? nil : JSON.parse(raw)
+
+  if payload.is_a?(Hash)
+    tmp_root = ENV["PLASTIC_TMP"].to_s.empty? ? Dir.tmpdir : ENV["PLASTIC_TMP"]
+    plastic_home = File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
+
+    # PLASTIC_HOOK_TRACE=<file> (331a1): opt-in, off by default, one JSON
+    # object appended per chunk. This script is the only place allowed to
+    # read the environment; MessageDisplay takes the sink as an argument.
+    trace_path = ENV["PLASTIC_HOOK_TRACE"].to_s
+    trace = trace_path.empty? ? nil : MessageDisplay.file_trace(trace_path)
+
+    handler = MessageDisplay.new(
+      tmp_root: tmp_root,
+      plastic_home: plastic_home,
+      color: color_enabled?(plastic_home),
+      now: Time.now,
+      trace: trace,
+    )
+    result = handler.handle(payload)
+
+    if result.is_a?(String)
+      puts JSON.generate(
+        "hookSpecificOutput" => {
+          "hookEventName" => "MessageDisplay",
+          "displayContent" => result,
+        },
+      )
+    end
+  end
+rescue StandardError
+  nil
+end
+exit 0

package/scripts/hook-record

@@ -135,13 +135,21 @@ unless skip_day_ledger
   end
 end
 
-# --- (d) heartbeat, always -------------------------------------------------
+# --- (d) heartbeat, guarded on the pointer (spec D9) -----------------------
+# Session start writes the `current` pointer; with no pointer at all, session
+# start never ran for this session (a `-p` print session, a resumed
+# background job, an unregistered SessionStart hook), so neither the
+# per-session dir nor its heartbeat is created here -- guarding only the
+# write would still leave an empty directory that heartbeat_age's mtime
+# fallback reports as an orphan just the same.
 begin
   store ||= File.join(plastic_home, "store")
   sid ||= SessionLedger.short_session_id(nil, session_id)
-  SessionLedger.ensure_tmp_root(store)
-  FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
-  File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  if File.exist?(SessionLedger.pointer_path(store, sid))
+    SessionLedger.ensure_tmp_root(store)
+    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+    File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  end
 rescue StandardError
   nil
 end

package/scripts/hook-session-start

@@ -18,6 +18,40 @@ 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 : ""
+
+# --- subagent marker (intent 355 spec D9, node n7; review fix n8, B6): the
+# stdin payload carries agent_id only when this SessionStart call runs
+# inside a spawned agent. agent_type alone is not enough: a live
+# `claude --agent` session carries agent_type on every turn but never
+# agent_id, so keying on agent_type would boot a live agent session with the
+# core banner only. Read from that payload only, never from an environment
+# variable, so a helper needs the core banner alone. An absent agent_id (the
+# common case) is a live session. Any exception here still boots the banner,
+# never nothing: the rescue falls back to a live session, whose own content
+# already comes from paths this file already guards independently.
+subagent_session = begin
+  stdin_payload.is_a?(Hash) && !!stdin_payload["agent_id"]
+rescue StandardError
+  false
+end
+
 # 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
@@ -236,9 +270,9 @@ begin
   end
 rescue Exception
   # Any failure (timeout, missing binary, parse error) — stay silent, never crash.
-end
+end unless subagent_session
 
-if plastic_md
+if plastic_md && !subagent_session
   # Conventions always loaded first
   parts << plastic_md
   parts << "\n---\n"
@@ -274,7 +308,7 @@ if plastic_md
   end
 end
 
-if active_deprecations.any?
+if active_deprecations.any? && !subagent_session
   parts << ""
   active_deprecations.each do |dep|
     severity = dep["severity"] || "info"
@@ -301,7 +335,7 @@ if active_deprecations.any?
   end
 end
 
-if update_notice
+if update_notice && !subagent_session
   parts.unshift("! #{update_notice}\n")
 end
 
@@ -349,7 +383,7 @@ begin
   end
 rescue StandardError
   nil
-end
+end unless subagent_session
 
 # --- Session day ledger: open or join today, write the per-session pointer
 # and heartbeat (intent 298, spec D4). Best-effort: any failure here degrades
@@ -361,7 +395,11 @@ begin
   author = "session" if author.empty?
   SessionLedger.open_day(store: store_dir, day: day, templates: templates, author: author)
 
-  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
+  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))
@@ -394,7 +432,7 @@ begin
   end
 rescue StandardError
   nil
-end
+end unless subagent_session
 
 # Emit nothing when there is genuinely nothing to surface (no conventions,
 # no deprecations, no update notice).

package/scripts/index-projection

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# index-projection - the CLI over IndexProjection (intent 337, G4): prints
+# the drift between INDEX.md and the intent ledgers for one store root
+# (INDEX.md plus a store/ directory), exits non-zero when any drift exists.
+# --write renders INDEX.md's four status sections from the projection
+# through AtomicWrite; every other byte, including ## Clusters and
+# ## Relocated, is untouched.
+#
+# Usage:
+#   index-projection <store_root> [--write]
+#
+# Exit codes:
+#   0 - no drift (or, with --write, the write landed cleanly)
+#   1 - drift exists (a real terminal-ledger conflict, an INDEX entry with
+#       no directory, or a directory INDEX does not list)
+#   2 - usage: no argument, or the path is not a store root
+
+require_relative "lib/index_projection"
+
+module IndexProjectionCli
+  module_function
+
+  def usage
+    warn "Usage: index-projection <store_root> [--write]"
+  end
+
+  def main(argv)
+    args = argv.dup
+    write = !!args.delete("--write")
+
+    root = args.shift
+    unless root && Dir.exist?(root)
+      warn "index-projection: #{root.inspect} is not a store root"
+      usage
+      return 2
+    end
+
+    index_path = File.join(root, "INDEX.md")
+    store_dir = File.join(root, "store")
+    unless File.exist?(index_path)
+      warn "index-projection: no INDEX.md at #{index_path}"
+      return 2
+    end
+
+    if write
+      result = IndexProjection.write(store_dir, index_path: index_path)
+      unless result[:ok]
+        warn "index-projection: #{result[:error]}"
+        return 2
+      end
+      puts "index-projection: wrote #{index_path} (#{result[:moved].length} moved)"
+      return 0
+    end
+
+    analysis = IndexProjection.analyze(store_dir, index_path: index_path)
+    print_report(analysis)
+
+    (analysis[:drift].empty? && analysis[:index_only].empty? && analysis[:directory_only].empty?) ? 0 : 1
+  end
+
+  def print_report(analysis)
+    puts "Drift (#{analysis[:drift].length}):"
+    analysis[:drift].each { |r| puts "  #{r[:id]}: INDEX=#{r[:index_status]} ledger=#{r[:ledger_status]}" }
+    puts "INDEX-only (#{analysis[:index_only].length}):"
+    analysis[:index_only].each { |r| puts "  #{r[:id]} (#{r[:index_status]})" }
+    puts "Directory-only (#{analysis[:directory_only].length}):"
+    analysis[:directory_only].each { |r| puts "  #{r[:id]}" }
+  end
+end
+
+exit(IndexProjectionCli.main(ARGV)) if $PROGRAM_NAME == __FILE__

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/action_graph_shim.rb

@@ -0,0 +1,277 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_file"
+require_relative "savepoint"
+require_relative "work_graph_validator"
+
+# ActionGraphShim (intent 342, G9): a read-time backward shim that presents
+# any intent directory's actions/*.md as a node graph, in the record shape
+# NodeFile.parse returns, so 336, 338 and 339 read a legacy intent through
+# the same call they already use for an authored graph.md (spec.md D1-D18).
+#
+# Writes nothing, anywhere, ever (D1). An authored graph.md always wins over
+# the synthetic chain (D3) - the reverse of 334's forward shim, which
+# resolves content and prefers the older, richer source. This one resolves
+# structure, where an authored graph is the only real graph.
+module ActionGraphShim
+  module_function
+
+  # D10's heading test: unchanged, four tokens, verified correct on the live
+  # store. Governs only whether a "## Files ..." heading itself is negated
+  # (e.g. "## Files you must NOT change"), never the section body.
+  FILES_NEGATION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't/i.freeze
+
+  # D19's body-truncation vocabulary: the four heading tokens plus the
+  # exclusion phrases the live corpus actually uses ("Out of bounds, owned
+  # by leads running in parallel right now:" matched none of the original
+  # four). Governs whether a body LINE truncates the files harvest -
+  # never the heading test above, which stays on FILES_NEGATION_RE.
+  FILES_EXCLUSION_RE = /\bnot\b|\bnever\b|\bavoid\b|don't|\bout of bounds\b|\bout of scope\b|\bhands off\b|\bleave alone\b|\bexcluded\b/i.freeze
+
+  BACKTICK_RE = /`([^`]+)`/.freeze
+  PROVEN_BY_LABEL_RE = /\AS\d+\z/.freeze
+
+  # :authored when graph.md exists, :actions when it does not but the intent
+  # holds at least one real action file (D7's exact realness test, reused
+  # rather than reimplemented so the shim can never disagree with
+  # Savepoint.has_real_action? about whether an intent has work in it), :none
+  # otherwise. A directory that does not exist returns :none and never
+  # raises.
+  def shape(intent_dir)
+    return :none unless intent_dir && File.directory?(intent_dir.to_s)
+    return :authored if File.exist?(File.join(intent_dir, "graph.md"))
+    return :actions if Savepoint.has_real_files_in?("actions", intent_dir)
+
+    :none
+  end
+
+  # The seven-key hash GraphFile.parse returns (ok:, goal:, decisions:,
+  # graph:, status:, verify:, errors:), for whichever shape the directory
+  # is in. On :authored this is literally GraphFile.parse, unmodified (D3).
+  # On :actions the same hash is built from the action files, with goal:,
+  # decisions: and status: nil (a 2024 action file was never asked for
+  # them) and verify: a fixed reason so a trivial-bar check the caller may
+  # run stays self-consistent. On :none it is GraphFile.parse's own
+  # not-found failure, produced by delegating to it rather than
+  # reformatting the message ourselves.
+  def view(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    when :actions
+      synth = synthetic_graph(intent_dir)
+      {
+        ok: synth[:errors].empty?,
+        goal: nil,
+        decisions: nil,
+        graph: synth,
+        status: nil,
+        verify: { reason: "backward shim: legacy actions/ carry no verify node" },
+        errors: synth[:errors],
+      }
+    else
+      # 342 post-execution review, should-fix 5: a nil intent_dir must never
+      # raise. shape(nil) is already nil-guarded, so `view` and `needs`
+      # honor the same contract rather than raising a File.join TypeError.
+      return GraphFile.failure(["graph file not found: #{intent_dir.inspect}"]) unless intent_dir
+
+      GraphFile.parse(File.join(intent_dir, "graph.md"))
+    end
+  end
+
+  # Node records for either shape (D8), always carrying NodeFile.parse's own
+  # key set (ok:, node:, kind:, files:, budget:, body:, errors:) plus
+  # needs:, path: and proven_by:. [] on :none, never a raise on a real
+  # directory.
+  def nodes(intent_dir)
+    case shape(intent_dir)
+    when :authored
+      authored_nodes(intent_dir)
+    when :actions
+      synthetic_nodes(intent_dir)
+    else
+      []
+    end
+  end
+
+  # The needs targets for one node id, under either shape; [] for an id the
+  # graph does not declare, and [] for a directory with no graph at all.
+  def needs(intent_dir, node_id)
+    graph = view(intent_dir)[:graph]
+    return [] unless graph
+
+    (graph[:edges] || {})[node_id] || []
+  end
+
+  # --- authored shape -------------------------------------------------------
+
+  def authored_nodes(intent_dir)
+    parsed = GraphFile.parse(File.join(intent_dir, "graph.md"))
+    edges = parsed.dig(:graph, :edges) || {}
+
+    # 342 post-execution review, nit 8: sort_key numerically over the
+    # basename, the same key the synthetic chain uses, so an authored
+    # intent with ten or more nodes orders n10 after n9 rather than
+    # lexically between n1 and n2.
+    Dir.glob(File.join(intent_dir, "nodes", "*.md"))
+       .sort_by { |path| sort_key(File.basename(path)) }
+       .map do |path|
+      nf = NodeFile.parse(path)
+      nf.merge(
+        needs: edges[nf[:node]] || [],
+        path: path,
+        proven_by: proven_by_labels(nf[:body].to_s)
+      )
+    end
+  end
+
+  # --- actions shape ----------------------------------------------------------
+
+  # {nodes:, edges:, errors:} built directly over the minted chain, in the
+  # same shape GraphEdges.parse returns, rather than rendering a "## Graph"
+  # section and reparsing it.
+  def synthetic_graph(intent_dir)
+    ids = real_action_files(intent_dir).each_index.map { |i| "n#{i + 1}" }
+    edges = {}
+    ids.each_with_index { |id, i| edges[id] = i.zero? ? [] : [ids[i - 1]] }
+    { nodes: ids, edges: edges, errors: [] }
+  end
+
+  def synthetic_nodes(intent_dir)
+    files = real_action_files(intent_dir)
+    files.each_with_index.map do |path, i|
+      id = "n#{i + 1}"
+      needs_targets = i.zero? ? [] : ["n#{i}"]
+      begin
+        text = File.read(path)
+        {
+          ok: true,
+          node: id,
+          kind: "work",
+          files: files_section_paths(text),
+          budget: nil,
+          body: text,
+          errors: [],
+          needs: needs_targets,
+          path: path,
+          proven_by: proven_by_labels(text),
+        }
+      rescue StandardError => e
+        {
+          ok: false,
+          node: id,
+          kind: "work",
+          files: [],
+          budget: nil,
+          body: nil,
+          errors: ["could not read #{path}: #{e.message}"],
+          needs: needs_targets,
+          path: path,
+          proven_by: [],
+        }
+      end
+    end
+  end
+
+  # Real action files (File.file?, non-zero size, Savepoint.stage_file_present?
+  # - D7's own three-part predicate, applied per file since has_real_files_in?
+  # only answers true/false), ordered by the integer trailing the basename,
+  # falling back to the basename itself so the key is a total order over
+  # every basename shape the live store holds (D4).
+  def real_action_files(intent_dir)
+    Dir.glob(File.join(intent_dir.to_s, "actions", "*.md"))
+       .select { |f| File.file?(f) && File.size(f) > 0 && Savepoint.stage_file_present?(f) }
+       .sort_by { |f| sort_key(File.basename(f)) }
+  end
+
+  def sort_key(basename)
+    m = basename.match(/\d+/)
+    m ? [0, m[0].to_i, basename] : [1, 0, basename]
+  end
+
+  # The first heading whose leading token is "Files" (case-insensitively),
+  # unless the heading text carries a negation, in which case it is not a
+  # files section and the search continues (D10). Paths come out of that
+  # section's BODY through extract_files_paths, which is itself
+  # negation-aware and fence-aware (D17, D18). No qualifying heading gives
+  # [] (D9).
+  def files_section_paths(text)
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless files_heading?(heading)
+
+      return extract_files_paths(section.to_s)
+    end
+    []
+  end
+
+  # Fence-aware (D18) and negation-aware over the section body, not only
+  # its heading (D17). D10 already stops a heading like "## Files you must
+  # NOT change" from being read as a files section at all; this handles
+  # the equally common case where a legitimate "## Files to touch" heading
+  # is followed, inside the same section, by an out-of-bounds paragraph -
+  # live on this intent's own dogfood fixture. A fenced block is dropped
+  # before anything else runs, reusing NodeFile.each_fence_line rather than
+  # a bare backtick scan, which is exactly what that helper exists to
+  # prevent.
+  #
+  # Lines are scanned in document order; harvesting stops at the first line
+  # an exclusion GOVERNS (D19), not merely mentions - a negation is a false
+  # positive as often as a real exclusion clause, since an action file
+  # routinely annotates an in-bounds path with a "do NOT rename it" aside.
+  # governs_exclusion? draws the line: the match governs when it begins
+  # before the line's first backtick (an exclusion clause introducing
+  # paths) or when the line carries no backtick at all (a bare warning
+  # sentence); it annotates, and the line is kept, when the match falls
+  # after the first backtick (a parenthetical about a path already named).
+  # Any span that still holds a newline is rejected as a backstop: a path
+  # is never more than one line.
+  def extract_files_paths(section)
+    kept = +""
+    NodeFile.each_fence_line(section) do |line, fenced|
+      next if fenced
+      break if governs_exclusion?(line)
+
+      kept << line
+    end
+    kept.scan(BACKTICK_RE).flatten.reject { |s| s.include?("\n") }.uniq
+  end
+
+  # True when a FILES_EXCLUSION_RE match on this line governs the paths on
+  # it rather than merely annotating one (D19).
+  def governs_exclusion?(line)
+    match = line.match(FILES_EXCLUSION_RE)
+    return false unless match
+
+    first_backtick = line.index("`")
+    first_backtick.nil? || match.begin(0) < first_backtick
+  end
+
+  def files_heading?(heading)
+    stripped = heading.to_s.sub(/\A#+\s*/, "")
+    first_token = stripped.split(/\s+/, 2).first.to_s.sub(/[^A-Za-z]+\z/, "")
+    return false unless first_token.casecmp?("Files")
+
+    !heading.to_s.match?(FILES_NEGATION_RE)
+  end
+
+  # The S\d+ tokens of a file's headings, in heading order, taking a
+  # heading only when it owns at least one table data row (D5) - the same
+  # table-owning rule WorkGraphValidator.has_valid_matrix? and ReportScreen
+  # already apply, reused unmodified rather than adapted, so a prose
+  # mention of an S-label never manufactures a Proven-by source (334's
+  # post-execution review defect, in the other direction).
+  def proven_by_labels(text)
+    labels = []
+    NodeFile.split_by_headings(text).each do |heading, section|
+      next unless NodeFile.table_rows(section).any?
+
+      WorkGraphValidator.heading_tokens(heading).each do |token|
+        labels << token if token.match?(PROVEN_BY_LABEL_RE)
+      end
+    end
+    labels
+  end
+end

package/scripts/lib/arm.rb

@@ -94,8 +94,21 @@ module Arm
     }
   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))
@@ -125,12 +138,24 @@ module Arm
   # 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)
+          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)