kairos-chain 3.89.0 → 3.90.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 109c03e66d55828499533b9d00945390f97cfd8aa56376aa898c099a30218316
-  data.tar.gz: 3013372fe35ae2bf4e3e5a4267fed64197e7480da32f2030664eb61766724f44
+  metadata.gz: b1f38307df012164fc2070ff3a5a7489f651c678e4bcb75f4d93ef2ba65dec6d
+  data.tar.gz: 11f40f3abe1a502600d451ffb4e6fe757f1cd351fa7f9af7c4c09fe0669f776c
 SHA512:
-  metadata.gz: 824d9d93d7e2c22a991e116a2f8c66acf8d54ecb2469a541c2f51a0ae982b0018d2650f88931daa5cf6da2091bba5ed470e13334c7b341d09fdfa2a7f48c01f8
-  data.tar.gz: bcc18d3c8123b54db6b934fc475f8517a7cd3dc2562a34d213c37140f08b45218d461c3685216f6577e9683de111f7ec70a07f9da27e5bfe947d0e740caffc5f
+  metadata.gz: 5886c559503ae2223da85857a13e8fa2b365271f5988c3a24b77675ce56215ca481fb581d60f82f523dfe9a1cce4fb81e8b5cfc70f81fb68beec4142183c4450
+  data.tar.gz: de3e9624a91ef9bbc9eaf3712cf64e6367f8b13523c1f3ace774cd31d0c7be4aa5560d60d7f8bfda9197802165dea0ab8a5dd7c74cb2bf666f4c903b26603249

data/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.90.0] - 2026-10-07
+
+### Added — agent: every answer is a ruling on the chain, and an answer typed at a terminal binds
+
+Until now the gate log kept which answer advanced a session, but not who gave
+it, why, or what it was given to. **Every answer that advances an agent session
+is now recorded on the chain as a ruling** (`agent_answer`) — through
+`agent_step` (approve, revise, skip, stop, adjudicate) and `agent_stop` alike.
+
+- **What a ruling holds**: the point it answered (state, cycle, and why the
+  session was waiting), the plan's SHA-256 and the driver's own signals when a
+  plan was the subject, the act-route table in force, the decision, and whether
+  it was attested. A replayed retry writes none. A ruling that fails to record
+  never blocks the answer; the response says so under `ruling`. Reasons
+  (`rationale`, new optional argument) and revise feedback stay off the chain;
+  the ruling carries their SHA-256.
+- **Answer as yourself, at a terminal**:
+
+      ruby .kairos/skillsets/agent/bin/agent_rule.rb answer SESSION_ID
+
+  It shows why the session stopped and the whole plan (every argument, escaped,
+  and the file it is kept in), asks for your answer, an optional reason and a
+  nonce, and records the answer bound to that point and that plan. The answer
+  then sent through `agent_step` there must be the same one, or it is refused
+  (`answer_refused`); **a stop always goes through**. After a revise at the
+  terminal, send `revise` without feedback and your text is used. Pass
+  `--project-dir` when the MCP server runs in another directory than the
+  project holding its data dir. An answer sent only through MCP is recorded as
+  the caller's, unattested.
+- **Every waiting session says why it stopped** (`stop` in every response and in
+  `agent_status`). `cycle_checkpoint` means only the scheduled end-of-cycle
+  stop (Gate 8, or a manual act that succeeded and left nothing over); failed
+  acts, set-aside steps, guard halts, adjudications, risk pauses and the rest
+  name themselves.
+- **While the chain cannot be read, every answer but a stop is refused**,
+  because whether you answered at the terminal cannot be checked. On chain
+  stores other than the file ledger (sqlite, postgresql) the agent can only be
+  stopped.
+
+No action is needed after upgrading. Approval delegation (the shadow judge) is
+not part of this release; do not run the agent unattended.
+
 ## [3.89.0] - 2026-10-07
 
 ### Security — agent: the act route runs from an allow-list

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.89.0"
+  VERSION = "3.90.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/agent/bin/agent_rule.rb

@@ -1,17 +1,24 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 #
-# The operator's terminal ruling on the agent's act-route allow-list
-# (design v0.3, INV-A2 / INV-D8).
+# The operator's terminal rulings for the agent (design v0.3, INV-A2 / INV-D8):
+# the act-route allow-list, and answers at a stopped session.
 #
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb activate   # rule the current table into force
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb withdraw   # take it out of force
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb status     # show what is in force (records nothing)
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb answer SESSION_ID
+#                         # answer a stopped session; the MCP answer there must then match
 #
-# Options: --data-dir DIR   the instance data dir whose chain is written
-#                           (default: the .kairos this script is installed in)
+# Options: --data-dir DIR     the instance data dir whose chain is written
+#                             (default: the .kairos this script is installed in)
+#          --project-dir DIR  answer only: the directory the MCP server runs in,
+#                             whose .kairos/storage holds its agent sessions
+#                             (default: the directory holding the data dir).
+#                             Needed when the server runs with --data-dir
+#                             pointing at another project's .kairos.
 #
-# activate and withdraw read a nonce typed back at /dev/tty and refuse to run
+# activate, withdraw and answer read a nonce typed back at /dev/tty and refuse to run
 # without a terminal. That keeps an MCP call from producing a ruling through
 # this path. It does not prove a person typed: any process that can start
 # programs can open a pseudo-terminal, read the nonce and type it back (shown
@@ -21,8 +28,10 @@
 
 require 'json'
 
-action = ARGV.find { |a| %w[activate withdraw status].include?(a) }
-abort 'usage: agent_rule.rb activate|withdraw|status [--data-dir DIR]' unless action
+action = ARGV.find { |a| %w[activate withdraw status answer].include?(a) }
+abort 'usage: agent_rule.rb activate|withdraw|status|answer SESSION_ID [--data-dir DIR]' unless action
+session_id = action == 'answer' ? ARGV[ARGV.index('answer') + 1].to_s : nil
+abort 'usage: agent_rule.rb answer SESSION_ID [--data-dir DIR]' if session_id&.then { |s| s.empty? || s.start_with?('-') }
 
 idx = ARGV.index('--data-dir')
 data_dir = idx ? File.expand_path(ARGV[idx + 1].to_s) : File.expand_path('../../..', __dir__)
@@ -45,6 +54,27 @@ ac = KairosMcp::SkillSets::Agent::ActClassification
 path = ac::BASE_PATH
 
 puts "Data dir: #{data_dir}"
+if action == 'answer'
+  require 'kairos_mcp/invocation_context'
+  require File.join(lib, 'agent', 'session')
+  require File.join(lib, 'agent', 'advance_gate')
+  require File.join(lib, 'agent', 'answer_ruling')
+  # The server keeps agent sessions under <its working directory>/.kairos/storage
+  # (Session.storage_path without Autonomos loaded), and its chain under its
+  # data dir. The two can differ; the answer is read from the first and
+  # recorded on the second, the chain the server reads.
+  pidx = ARGV.index('--project-dir')
+  abort 'usage: agent_rule.rb answer SESSION_ID --project-dir DIR' if pidx && ARGV[pidx + 1].to_s.then { |v| v.empty? || v.start_with?('-') }
+  project_dir = pidx ? File.expand_path(ARGV[pidx + 1].to_s) : File.dirname(data_dir)
+  abort "no project dir at #{project_dir}" unless File.directory?(project_dir)
+  Dir.chdir(project_dir)
+  session = KairosMcp::SkillSets::Agent::Session.load(session_id)
+  unless session
+    abort "no agent session #{session_id} under #{File.join(Dir.pwd, '.kairos', 'storage', 'agent_sessions')} " \
+          '(if the MCP server runs in another directory, pass --project-dir)'
+  end
+  puts "Sessions from: #{project_dir}"
+end
 if action == 'status'
   eff = ac.load_effective(path: path)
   puts "Table #{ac::TABLE_ID}: #{eff['status']}"
@@ -62,7 +92,14 @@ rescue StandardError => e
 end
 
 begin
-  result = ac.interactive_rule(action: action, tty_in: tty, tty_out: tty, path: path)
+  result = if action == 'answer'
+             KairosMcp::SkillSets::Agent::AnswerRuling.interactive_answer(
+               session: session, gate: KairosMcp::SkillSets::Agent::AdvanceGate.new(session.guard_dir),
+               tty_in: tty, tty_out: tty, reload: -> { KairosMcp::SkillSets::Agent::Session.load(session_id) }
+             )
+           else
+             ac.interactive_rule(action: action, tty_in: tty, tty_out: tty, path: path)
+           end
 ensure
   tty.close
 end

data/templates/skillsets/agent/lib/agent/answer_ruling.rb

@@ -0,0 +1,481 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+require 'time'
+
+module KairosMcp
+  module SkillSets
+    module Agent
+      # Every answer at an approval point is a ruling on the chain
+      # (design v0.3, INV-D4 / INV-D8).
+      #
+      # Two record kinds:
+      #
+      #   agent_answer              one per committed advance, written by the
+      #                             driver when the advance commits. It is the
+      #                             ruling: it exists only for a decision that
+      #                             was carried out, and a replayed retry never
+      #                             writes a second one (it never commits).
+      #   agent_answer_attestation  the operator's answer typed at the terminal
+      #                             (bin/agent_rule.rb answer), bound to the
+      #                             anchor it was given at. While it is the
+      #                             latest one at that anchor, an MCP answer
+      #                             there proceeds only if it is the same
+      #                             answer; a stop always proceeds (operator
+      #                             ruling 2026-10-07: stopping is never
+      #                             refused) and is recorded as overriding it.
+      #
+      # Texts (revise feedback, rationale) stay off the chain in the session
+      # directory; records carry their sha256.
+      #
+      # Attestation boundary (INV-D8): 'terminal_nonce' records the path the
+      # answer came by. Any party that can write the chain could write a block
+      # of the same shape; the constrained party in phase 1 is the agent.
+      module AnswerRuling
+        KIND = 'agent_answer'
+        ATTESTATION_KIND = 'agent_answer_attestation'
+        TEXTS_FILE = 'answer_texts.jsonl'
+
+        # Why a session is waiting. Written with the state change that stops it
+        # (Session#update_state / #stop_at); a stop without one reads as
+        # 'unspecified'. cycle_checkpoint is the scheduled end-of-cycle stop
+        # (Gate 8 in autonomous mode, the end of an act with nothing left over
+        # in manual mode) and nothing else.
+        STOP_KINDS = %w[
+          session_started cycle_observed plan_proposed cycle_checkpoint cycle_skipped adjudicated
+          awaiting_operator guard_halt human_cognition_halt act_failed phase_error
+          risk_exceeded goal_drift timeout llm_budget_exceeded l0_escalation
+          review_rejected review_max_retries terminated
+        ].freeze
+
+        # States at which the persisted plan is the subject of the answer.
+        PLAN_STATES = %w[proposed checkpoint paused_risk].freeze
+
+        class << self
+          # Test seam: a callable returning [records, error]. nil in production.
+          attr_accessor :records_source
+        end
+
+        module_function
+
+        def sha256(text)
+          text.nil? || text.to_s.empty? ? nil : Digest::SHA256.hexdigest(text.to_s)
+        end
+
+        def plan_sha256(decision)
+          task = decision.is_a?(Hash) ? decision['task_json'] : nil
+          task.nil? ? nil : Digest::SHA256.hexdigest(JSON.generate(task))
+        end
+
+        # Answer records in chain order, each with the index of its block.
+        def records_from_blocks(blocks)
+          Array(blocks).flat_map do |block|
+            data = block.respond_to?(:data) ? block.data : (block['data'] || block[:data])
+            index = block.respond_to?(:index) ? block.index : (block['index'] || block[:index])
+            Array(data).filter_map do |entry|
+              rec = entry.is_a?(String) ? (JSON.parse(entry) rescue nil) : entry
+              next unless rec.is_a?(Hash) && [KIND, ATTESTATION_KIND].include?(rec['kind'])
+
+              rec.merge('block' => index)
+            end
+          end
+        end
+
+        # [records, nil], or [[], reason] when the chain cannot be read. The
+        # ledger is rewritten in place on every append, so a read that races a
+        # writer can see a torn file (measured in review, about 1 in 10,000
+        # reads under load); a read is retried before it is believed.
+        READ_ATTEMPTS = 3
+
+        def chain_records
+          return AnswerRuling.records_source.call if AnswerRuling.records_source
+
+          require 'kairos_mcp/kairos_chain/chain'
+          reason = nil
+          READ_ATTEMPTS.times do |i|
+            sleep(0.05 * i) if i.positive?
+            begin
+              chain = ::KairosMcp::KairosChain::Chain.new
+              state = chain.load_state
+              return [records_from_blocks(chain.chain), nil] if %i[readable absent].include?(state)
+
+              reason = "chain #{state}"
+            rescue StandardError => e
+              reason = "chain unreadable: #{e.class}: #{e.message[0, 120]}"
+            end
+          end
+          [[], reason]
+        rescue StandardError, ScriptError => e
+          [[], "chain unreadable: #{e.class}: #{e.message[0, 120]}"]
+        end
+
+        # An earlier ruling at the same anchor of the same session: only a
+        # crash between the chain write and the gate commit leaves one. The
+        # later ruling names it, so a count takes one ruling per anchor.
+        def prior_ruling_at(records, session_id, anchor)
+          Array(records).select do |r|
+            r['kind'] == KIND && r['session_id'] == session_id && r['anchor'] == anchor
+          end.last
+        end
+
+        # The operator's latest attested answer at this anchor, or nil.
+        def attestation_at(records, session_id, anchor)
+          Array(records).select do |r|
+            r['kind'] == ATTESTATION_KIND && r['attested'] == true &&
+              r['session_id'] == session_id && r['anchor'] == anchor
+          end.last
+        end
+
+        # Whether an answer arriving through MCP may proceed where the operator
+        # answered at the terminal. Returns { 'ok' => true, 'feedback',
+        # 'attestation' | 'overrode' } or { 'ok' => false, 'reason',
+        # 'attestation' }. A revise without feedback takes the text typed at the
+        # terminal, if its sha256 is the one the attestation names.
+        # check_plan: false for a call that targets an anchor the session has
+        # already left; such a call can only replay, and the plan has moved on.
+        def reconcile(attestation, action:, resolution: nil, feedback: nil, plan_sha256: nil, texts: nil,
+                      check_plan: true)
+          return { 'ok' => true, 'feedback' => feedback } unless attestation
+
+          if action == 'stop'
+            key = attestation['decision'] == 'stop' ? 'attestation' : 'overrode'
+            return { 'ok' => true, 'feedback' => feedback, key => attestation }
+          end
+          refuse = ->(why) { { 'ok' => false, 'reason' => why, 'attestation' => attestation } }
+          unless attestation['decision'] == action
+            return refuse.call("the operator answered #{attestation['decision']} at the terminal")
+          end
+          if action == 'adjudicate' && attestation['resolution'] != resolution
+            return refuse.call("the operator adjudicated #{attestation['resolution']} at the terminal")
+          end
+          if check_plan && attestation['plan_sha256'] && attestation['plan_sha256'] != plan_sha256
+            return refuse.call('the plan is not the one the operator answered at the terminal')
+          end
+          if action == 'revise'
+            want = attestation['feedback_sha256']
+            if feedback.to_s.empty?
+              text = Array(texts&.call).reverse.map { |t| t['feedback'] }.find { |f| want && sha256(f) == want }
+              return refuse.call('the feedback typed at the terminal is not available; send it with the answer') unless text
+
+              feedback = text
+            elsif sha256(feedback) != want
+              return refuse.call('the feedback differs from the one typed at the terminal')
+            end
+          end
+          { 'ok' => true, 'feedback' => feedback, 'attestation' => attestation }
+        end
+
+        # The ruling for a committed advance. point: { 'state', 'cycle', 'stop',
+        # and when a plan is the subject 'plan_sha256', 'signals', 'set_aside' }.
+        def ruling(session_id:, mandate_id:, anchor:, point:, action:, action_key:, tables:,
+                   answer: {}, feedback: nil, rationale: nil)
+          att = answer['attestation']
+          rec = {
+            'kind' => KIND, 'session_id' => session_id, 'mandate_id' => mandate_id,
+            'anchor' => anchor, 'state' => point['state'], 'cycle' => point['cycle'],
+            'stop' => point['stop'], 'decision' => action, 'decision_key' => action_key,
+            'approver' => att ? 'operator' : 'caller',
+            'attestation' => att ? 'terminal_nonce' : 'caller_unattested',
+            'tables' => tables, 'answered_at' => Time.now.utc.iso8601
+          }
+          rec['attestation_block'] = att['block'] if att
+          rec['overrode_attestation_block'] = answer['overrode']['block'] if answer['overrode']
+          rec['attestation_check'] = answer['read_error'][0, 160] if answer['read_error']
+          rec['supersedes_block'] = answer['prior_ruling_block'] if answer['prior_ruling_block']
+          %w[plan_sha256 signals set_aside].each { |k| rec[k] = point[k] if point.key?(k) }
+          rec['feedback_sha256'] = sha256(feedback) if action == 'revise'
+          # An attested ruling carries the operator's reason, typed at the
+          # terminal; a caller's text is not attributed to the operator.
+          reason = att ? att['rationale_sha256'] : sha256(rationale)
+          rec['rationale_sha256'] = reason if reason
+          rec
+        end
+
+        # Appends a record through the tool's chain_record. Never raises: a
+        # human answer is never blocked by a recording failure (INV-D4).
+        def record(tool, rec)
+          out = tool.invoke_tool('chain_record', { 'logs' => [JSON.generate(rec)] })
+          text = Array(out).map { |b| b[:text] || b['text'] }.compact.join
+          m = text.match(/Block #(\d+) recorded successfully\./)
+          return { 'recorded' => true, 'block' => m[1].to_i, 'attestation' => rec['attestation'] } if m
+
+          { 'recorded' => false, 'error' => "chain_record replied: #{text[0, 160]}",
+            'note' => 'the answer proceeded; this point does not count as evidence for delegation' }
+        rescue StandardError, ScriptError => e
+          { 'recorded' => false, 'error' => "#{e.class}: #{e.message[0, 160]}",
+            'note' => 'the answer proceeded; this point does not count as evidence for delegation' }
+        end
+
+        def save_texts(session_dir, anchor:, source:, feedback: nil, rationale: nil)
+          return if feedback.to_s.empty? && rationale.to_s.empty?
+
+          entry = { 'anchor' => anchor, 'source' => source, 'at' => Time.now.utc.iso8601 }
+          entry['feedback'] = feedback unless feedback.to_s.empty?
+          entry['rationale'] = rationale unless rationale.to_s.empty?
+          File.open(File.join(session_dir, TEXTS_FILE), 'a') { |f| f.puts(JSON.generate(entry)) }
+        end
+
+        def texts_at(session_dir, anchor, source: 'terminal')
+          path = File.join(session_dir, TEXTS_FILE)
+          return [] unless File.exist?(path)
+
+          File.foreach(path).filter_map do |line|
+            e = JSON.parse(line) rescue nil
+            e if e.is_a?(Hash) && e['anchor'] == anchor && e['source'] == source
+          end
+        end
+
+        # Agent-authored text as it may reach the operator's terminal: control
+        # and format characters (escape sequences, carriage returns, newlines,
+        # bidirectional overrides) are shown as escapes, so the text cannot
+        # move the cursor, erase lines, or reorder what the operator reads.
+        #
+        # Invalid bytes are replaced, so no string the agent writes can make
+        # the display raise. max caps text the answer does not bind (goal,
+        # stop detail); the plan is shown whole.
+        def printable(text, max = nil)
+          s = text.to_s.dup.force_encoding(Encoding::UTF_8).scrub('?')
+          s = s.gsub(/[[:cntrl:]\p{Cf}\p{Zl}\p{Zp}]|[\p{Zs}&&[^ ]]/) { |c| format('\\u{%x}', c.ord) }
+          max && s.length > max ? "#{s[0, max]}…" : s
+        end
+
+        def json_text(value)
+          JSON.generate(value)
+        rescue StandardError
+          value.inspect
+        end
+
+        # Argument names that say where a step acts; shown first.
+        LOCATION_NAME = /path|file|dir|root|source|destination|target|url|name/i
+
+        # The plan exactly as the attested hash covers it: every step with
+        # every argument, location arguments first, nothing cut; any other
+        # field of the task; and the file that holds it. The agent wrote all
+        # of it, so all of it is escaped, and the summary is marked as the
+        # plan's own claim rather than something the driver observed.
+        def show_plan(tty_out, decision, state, plan_sha, decision_path)
+          lines = []
+          out = Object.new
+          out.define_singleton_method(:puts) { |line = ''| lines << line.to_s }
+          plan_lines(out, decision, state, plan_sha, decision_path)
+          lines.each { |l| tty_out.puts l }
+          show_locations(tty_out, decision['task_json'], lines, decision_path)
+        end
+
+        # Where the plan acts, repeated last, next to the prompt. The agent
+        # wrote the plan above and controls its length and order, so it can
+        # push any line of it out of sight; this block is short by
+        # construction, so what the answer most depends on stays in view.
+        def show_locations(tty_out, task, lines, decision_path)
+          steps = task['steps'].is_a?(Array) ? task['steps'] : []
+          tty_out.puts
+          tty_out.puts "Where this plan acts (#{steps.size} step(s); each step's tool and location arguments):"
+          steps.each_with_index do |st, i|
+            unless st.is_a?(Hash)
+              tty_out.puts "  step #{i + 1}: (not a step; read the file)"
+              next
+            end
+            args = st['tool_arguments'].is_a?(Hash) ? st['tool_arguments'] : {}
+            locs = args.select { |k, _| k.to_s.match?(LOCATION_NAME) }
+            where = if locs.empty?
+                      '(no location argument)'
+                    else
+                      locs.map { |k, v| "#{printable(k, 30)}=#{visible(json_text(v))}" }.join(' ')
+                    end
+            tty_out.puts "  step #{i + 1}: #{printable(st['tool_name'], 40)} #{where}"
+          end
+          tty_out.puts "The plan above took #{lines.size} lines (#{lines.sum(&:length)} characters). If it scrolled " \
+                       "away, read it whole in #{File.expand_path(decision_path)}"
+        end
+
+        # A location value made legible: runs of spaces shown as a count, a
+        # long value cut with a marker that says so.
+        def visible(text, max = 120)
+          s = printable(text).gsub(/ {2,}/) { |m| "[#{m.size} spaces]" }
+          s.length > max ? "#{s[0, max]} (cut; read the file)" : s
+        end
+
+        def plan_lines(tty_out, decision, state, plan_sha, decision_path)
+          heading = { 'proposed' => 'Plan proposed (this answer decides whether it runs):',
+                      'paused_risk' => 'Plan stopped at the risk gate (this answer decides whether it runs):',
+                      'checkpoint' => 'Plan that has already run this cycle (approve starts the next cycle):' }
+          tty_out.puts heading[state] || 'Plan:'
+          tty_out.puts "  summary, as the plan states it: #{printable(decision['summary'])}"
+          task = decision['task_json']
+          steps = task['steps']
+          if steps.is_a?(Array)
+            steps.each_with_index do |st, i|
+              unless st.is_a?(Hash)
+                tty_out.puts "  step #{i + 1}: #{printable(json_text(st))}"
+                next
+              end
+              tty_out.puts "  step #{i + 1}: id #{printable(st['step_id'])}, tool #{printable(st['tool_name'])}"
+              args = st['tool_arguments']
+              if args.is_a?(Hash)
+                args.keys.sort_by { |k| k.to_s.match?(LOCATION_NAME) ? 0 : 1 }.each do |k|
+                  tty_out.puts "      #{printable(k)}: #{printable(json_text(args[k]))}"
+                end
+              elsif !args.nil?
+                tty_out.puts "      arguments: #{printable(json_text(args))}"
+              end
+              extra = st.reject { |k, _| %w[step_id tool_name tool_arguments].include?(k) }
+              tty_out.puts "      other fields: #{printable(json_text(extra))}" unless extra.empty?
+            end
+          else
+            tty_out.puts "  steps: #{printable(json_text(steps))}"
+          end
+          rest = task.reject { |k, _| k == 'steps' }
+          tty_out.puts "  other plan fields: #{printable(json_text(rest))}" unless rest.empty?
+          tty_out.puts "  The whole plan is in #{File.expand_path(decision_path)}"
+          tty_out.puts "  sha256 #{plan_sha}"
+        end
+
+        # The answers the terminal offers at a state.
+        def answers_for(effective_state, intent)
+          return [] if effective_state == 'terminated'
+          return %w[adjudicate stop] if intent
+
+          case effective_state
+          when 'proposed' then %w[approve revise skip stop]
+          when 'paused_risk', 'paused_error' then %w[approve skip stop]
+          else %w[approve stop]
+          end
+        end
+
+        # ---- the terminal answer (INV-D8) ----
+
+        # Shows the stop on tty_out, reads the answer, an optional reason and
+        # the nonce on tty_in, and records the attestation only when the nonce
+        # matches and the session is still at the anchor shown. reload: a
+        # callable returning the session as persisted now. Returns
+        # { 'recorded' => bool, ... }.
+        def interactive_answer(session:, gate:, tty_in:, tty_out:, reload:, chain: nil,
+                               nonce_value: ActClassification.nonce)
+          anchor = gate.current_anchor(session)
+          state = gate.effective_state(session)
+          intent = gate.unresolved_intent
+          offered = answers_for(state, intent)
+          if offered.empty?
+            tty_out.puts "Session #{session.session_id} is #{session.state}; there is nothing to answer."
+            return { 'recorded' => false, 'reason' => 'nothing_to_answer' }
+          end
+
+          decision = session.load_decision
+          plan_sha = PLAN_STATES.include?(state) ? plan_sha256(decision) : nil
+          stop = session.stop || {}
+          tty_out.puts "Session: #{printable(session.session_id)} (#{session.autonomous? ? 'autonomous' : 'manual'})"
+          tty_out.puts "Goal:    #{printable(session.goal_name)}"
+          tty_out.puts "Stopped: #{printable(session.state)}, cycle #{session.cycle_number}, " \
+                       "because #{printable(session.stop_kind)}"
+          tty_out.puts "         #{printable(stop['detail'], 300)}" if stop['detail']
+          tty_out.puts "Anchor:  #{anchor}"
+          if intent
+            tty_out.puts 'An act started and its outcome was never recorded. Answer adjudicate (reattempt or already_done) or stop.'
+          end
+          show_plan(tty_out, decision, state, plan_sha, session.send(:decision_path)) if plan_sha
+          tty_out.puts
+          tty_out.print "Your answer (#{offered.join(' / ')}): "
+          tty_out.flush
+          action = tty_in.gets.to_s.strip.downcase
+          unless offered.include?(action)
+            tty_out.puts 'Not one of the answers offered. Nothing was recorded.'
+            return { 'recorded' => false, 'reason' => 'not_offered' }
+          end
+
+          resolution = nil
+          feedback = nil
+          if action == 'adjudicate'
+            tty_out.print 'Resolution (reattempt / already_done): '
+            tty_out.flush
+            resolution = tty_in.gets.to_s.strip
+            unless %w[reattempt already_done].include?(resolution)
+              tty_out.puts 'Not a resolution. Nothing was recorded.'
+              return { 'recorded' => false, 'reason' => 'not_offered' }
+            end
+          elsif action == 'revise'
+            tty_out.print 'Feedback for the revision (one line): '
+            tty_out.flush
+            feedback = tty_in.gets.to_s.strip
+            if feedback.empty?
+              tty_out.puts 'A revision needs feedback. Nothing was recorded.'
+              return { 'recorded' => false, 'reason' => 'empty_feedback' }
+            end
+          end
+          tty_out.print 'Reason (optional, one line, kept off the chain): '
+          tty_out.flush
+          rationale = tty_in.gets.to_s.strip
+
+          tty_out.print "Type #{nonce_value} to record this answer (anything else cancels): "
+          tty_out.flush
+          unless tty_in.gets.to_s.strip == nonce_value
+            tty_out.puts 'Cancelled. Nothing was recorded.'
+            return { 'recorded' => false, 'reason' => 'nonce_mismatch' }
+          end
+
+          record = {
+            'kind' => ATTESTATION_KIND, 'session_id' => session.session_id, 'anchor' => anchor,
+            'state' => session.state, 'stop' => session.stop_kind, 'decision' => action,
+            'attested' => true, 'attestation' => 'terminal_nonce', 'ruled_at' => Time.now.utc.iso8601
+          }
+          record['resolution'] = resolution if resolution
+          record['plan_sha256'] = plan_sha if plan_sha
+          record['feedback_sha256'] = sha256(feedback) if feedback
+          record['rationale_sha256'] = sha256(rationale) if sha256(rationale)
+
+          # Recorded under the advance lock, and only if no advance moved the
+          # session while the operator was typing.
+          result = gate.with_lock do
+            now = reload.call
+            if now.nil? || gate.current_anchor(now) != anchor
+              next { 'recorded' => false, 'reason' => 'moved_on',
+                     'detail' => "the session moved to #{now ? gate.current_anchor(now) : 'nowhere'}" }
+            end
+            # What was shown must still be what is answered: an act can open
+            # its intent, or a plan be rewritten, without the anchor moving.
+            now_state = gate.effective_state(now)
+            unless answers_for(now_state, gate.unresolved_intent).include?(action)
+              next { 'recorded' => false, 'reason' => 'moved_on',
+                     'detail' => "#{action} is no longer an answer this session can take" }
+            end
+            if (PLAN_STATES.include?(now_state) ? plan_sha256(now.load_decision) : nil) != plan_sha
+              next { 'recorded' => false, 'reason' => 'moved_on', 'detail' => 'the plan changed after it was shown' }
+            end
+
+            record['state'] = now.state
+            record['stop'] = now.stop_kind
+            save_texts(session.guard_dir, anchor: anchor, source: 'terminal', feedback: feedback, rationale: rationale)
+            chain ||= begin
+              require 'kairos_mcp/kairos_chain/chain'
+              ::KairosMcp::KairosChain::Chain.new
+            end
+            begin
+              block = chain.add_block([JSON.generate(record)])
+            rescue StandardError => e
+              next { 'recorded' => false, 'reason' => 'chain_refused', 'detail' => "#{e.class}: #{e.message[0, 160]}" }
+            end
+            { 'recorded' => true, 'block_index' => block.index, 'record' => record }
+          end
+
+          if result['status'] == 'busy'
+            tty_out.puts 'An advance is in flight on this session. Nothing was recorded; try again when it settles.'
+            return { 'recorded' => false, 'reason' => 'busy' }
+          end
+          unless result['recorded']
+            if result['reason'] == 'chain_refused'
+              tty_out.puts "The chain did not take the answer (#{result['detail']}). Nothing was recorded."
+            else
+              tty_out.puts "The session moved on while you were answering (#{result['detail']}). Nothing was recorded."
+            end
+            return result
+          end
+
+          tty_out.puts "Recorded as block ##{result['block_index']}."
+          tty_out.puts "Now send #{action}#{resolution ? " (#{resolution})" : ''} at this anchor (agent_step). " \
+                       'A different answer here is refused; a stop always goes through.'
+          result
+        end
+      end
+    end
+  end
+end