kairos-chain 3.17.0 → 3.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d2b6b702508caf49a43e1fdc09beb4b6d5a7dd478a89492d07503643744855c
-  data.tar.gz: faaceed727c7de49424391d32768bff4790411a414cd4b2a671fcd31501aadf5
+  metadata.gz: 35124b7f595066816a5e59823ca5f871bcb2c009f12db8127f7570ee0e923206
+  data.tar.gz: 482cef573f07539663a119db81cbdcb5b600362a551b3ee45459d9727c78c755
 SHA512:
-  metadata.gz: 727829e5b3672c2b694336baabb14af1a0906ee3b7c196bb320ea0060db98bc163ab36a7971f405eb88e0c1d0393dcb370fed337bb6220e0e8dd1716885e7166
-  data.tar.gz: 12be3d20add101e4ac13871b4c36dce043e104fcbe67ab1af95ad55793b018b2cc0e785324d34a4f8887a2969c7d6b5db9da61a9f777496d560296a8d94f14cc
+  metadata.gz: a07f31d1e33713c4993aaf396838ffaac1ac5c9979ba7ff24f0d590a39fa4341f64cb1899d061507cc13b7fdfff3a85ee6177dc21b54578a7ef2af9b8de5fe81
+  data.tar.gz: aebf6ebc84bf36682c74ebf7b000c5168051cab9685842c75dcd2a9ebc4b733713b4f1389e7e2d8fe00f61eefd3dc201885e9582a620c77e937a53999b349e3b

data/bin/kairos-chain-daemon

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# encoding: utf-8
+
+# KairosChain 24/7 daemon entry point (Bootstrap layer, v0.4 §2.2).
+#
+# Bootstrap's job:
+#   1. Load the gem and scan .kairos/skillsets/.
+#   2. Find a SkillSet that declares the :daemon_main lifecycle hook.
+#   3. Install OS signal traps for TERM/INT (shutdown), HUP (reload),
+#      USR2 (diagnostic snapshot) and forward them as flags on the
+#      Bootstrap SignalHandle.
+#   4. Hand control to the SkillSet's main loop.
+#
+# Everything substantive (OODA cycle, Chronos, WAL, attach endpoint,
+# safe-mode, canary promotion) lives in SkillSets — not here.
+
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+require 'optparse'
+
+options = { data_dir: nil }
+OptionParser.new do |opts|
+  opts.banner = 'Usage: kairos-chain-daemon [--data-dir PATH]'
+  opts.on('--data-dir PATH', 'Override .kairos/ location') { |v| options[:data_dir] = v }
+  opts.on('-h', '--help') do
+    puts opts
+    exit 0
+  end
+end.parse!
+
+if options[:data_dir]
+  if options[:data_dir].to_s.strip.empty?
+    warn '[kairos-chain-daemon] --data-dir must not be empty'
+    exit 4
+  end
+  expanded = File.expand_path(options[:data_dir])
+  # R2 P3 (Codex/4.7): reject a path that points to an existing regular
+  # file (or any non-directory). Either the directory exists, or its
+  # parent exists (so the daemon can create it), and in no case may the
+  # path itself be a non-directory.
+  if File.exist?(expanded) && !File.directory?(expanded)
+    warn "[kairos-chain-daemon] --data-dir is not a directory: #{expanded}"
+    exit 4
+  end
+  unless File.directory?(expanded) || File.directory?(File.dirname(expanded))
+    warn "[kairos-chain-daemon] --data-dir parent does not exist: #{expanded}"
+    exit 4
+  end
+  options[:data_dir] = expanded
+end
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'kairos_mcp'
+require 'kairos_mcp/signal_handle'
+require 'kairos_mcp/lifecycle_hook'
+require 'kairos_mcp/tool_registry'
+
+KairosMcp.data_dir = options[:data_dir] if options[:data_dir]
+
+begin
+  registry = KairosMcp::ToolRegistry.new
+rescue KairosMcp::LifecycleHook::Conflict => e
+  warn "[kairos-chain-daemon] #{e.message}"
+  warn '[kairos-chain-daemon] Disable one of the conflicting SkillSets and retry.'
+  exit 3
+end
+
+begin
+  klass = registry.lifecycle_hook_class(:daemon_main)
+rescue KairosMcp::LifecycleHook::UnknownClass => e
+  warn "[kairos-chain-daemon] lifecycle hook lookup failed: #{e.message}"
+  exit 3
+end
+
+unless klass
+  warn '[kairos-chain-daemon] 24/7 daemon runtime SkillSet not installed.'
+  warn '[kairos-chain-daemon] Install a SkillSet declaring lifecycle_hooks.daemon_main ' \
+       '(e.g. daemon_runtime).'
+  exit 2
+end
+
+# R9→R10 (Codex P1 / 4.6 P2): use the shared helper so bin/ gets the
+# pathological-return guard. Narrow rescue around ONLY the instantiation
+# (not the class lookup). Distinct exit codes:
+#   3 = lookup failure
+#   9 = instantiation failure (R9 P3 4.7 distinction ask)
+begin
+  runtime = registry.instantiate_lifecycle_hook(klass)
+rescue KairosMcp::LifecycleHook::InstanceViolation => e
+  # R10→R11 (Codex P1): distinct exception class for wrong-type return.
+  warn "[kairos-chain-daemon] lifecycle hook produced wrong type: #{e.message}"
+  exit 9
+rescue StandardError => e
+  warn "[kairos-chain-daemon] lifecycle hook instantiation failed: " \
+       "#{e.class}: #{e.message}"
+  exit 9
+end
+
+signal = KairosMcp::SignalHandle.new
+# R1 P1 (3-voice): trap HUP and USR2 so the reload/diagnostic paths in
+# SignalCoordinator are actually reachable from the real process.
+{ 'TERM' => :request_shutdown,
+  'INT'  => :request_shutdown,
+  'HUP'  => :request_reload,
+  'USR2' => :request_diagnostic }.each do |sig, m|
+  Signal.trap(sig) { signal.public_send(m) }
+end
+
+runtime.run_main_loop(registry: registry, signal: signal)

data/lib/kairos_mcp/lifecycle_hook.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  # LifecycleHook protocol (24/7 v0.4 §2.3).
+  #
+  # A SkillSet advertises one or more lifecycle hooks in its skillset.json:
+  #
+  #   {
+  #     "name": "daemon_runtime",
+  #     "lifecycle_hooks": { "daemon_main": "KairosMcp::SkillSets::DaemonRuntime::MainLoop" }
+  #   }
+  #
+  # Only one SkillSet may claim a given hook name. Conflicts raise at load
+  # time (Conflict) — silent override would violate the audit guarantees of
+  # the Bootstrap layer.
+  module LifecycleHook
+    class Conflict < StandardError; end
+    class NotImplementedHook < StandardError; end
+    # Lookup-phase failures (class not defined, not a Class, does not
+    # include LifecycleHook when resolved from the constant).
+    class UnknownClass < StandardError; end
+    class ForbiddenNamespace < StandardError; end
+    # R10→R11 (Codex P1): distinct exception for instantiation-phase
+    # contract violations — specifically, a `.new` override that returns
+    # an object not including LifecycleHook. Distinguishes programmatic
+    # callers from lookup failures and lets bin/ map to a different
+    # exit code without relying on call-site context.
+    class InstanceViolation < StandardError; end
+
+    # Allowlist for class-name resolution (R1 P1, 2-voice security):
+    # skillset.json is untrusted input, so `Object.const_get` must not
+    # instantiate arbitrary classes. Only classes under these namespaces
+    # may be bound to a lifecycle hook.
+    ALLOWED_NAMESPACES = [
+      'KairosMcp::SkillSets::'
+    ].freeze
+
+    # Valid Ruby constant path: Foo::Bar::Baz (no leading colons).
+    CLASS_NAME_RE = /\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/
+
+    def self.validate_class_name!(class_name)
+      name = class_name.to_s
+      unless name =~ CLASS_NAME_RE
+        raise UnknownClass, "invalid class name: #{class_name.inspect}"
+      end
+      unless ALLOWED_NAMESPACES.any? { |prefix| name.start_with?(prefix) }
+        raise ForbiddenNamespace,
+              "class '#{name}' is not under an allowed namespace " \
+              "(#{ALLOWED_NAMESPACES.join(', ')})"
+      end
+      name
+    end
+
+    # Contract an implementing class must fulfill.
+    # Bootstrap calls run_main_loop(registry:, signal:) and expects the
+    # callee to block until signal.shutdown_requested? is true, then return.
+    def run_main_loop(registry:, signal:)
+      raise NotImplementedHook, "#{self.class} must implement run_main_loop"
+    end
+  end
+end

data/lib/kairos_mcp/signal_handle.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  # Async-signal-safe signal flag bundle for the Bootstrap layer
+  # (24/7 v0.4 §2.2). Carries three one-way signals (shutdown / reload /
+  # diagnostic) across the signal-trap boundary.
+  #
+  # Async-signal safety:
+  # - `shutdown` is a one-way latch — set in trap, never cleared.
+  # - `reload` and `diagnostic` are edge-triggered. To avoid losing an
+  #   edge when a signal arrives mid-consume, they are tracked with a
+  #   ticket counter pattern (R2 Codex P1):
+  #     • trap handler: `@reload_seen += 1` (increment-only)
+  #     • consumer: diff = seen − consumed; consumed += diff
+  #   A signal firing between the consumer's read of `seen` and its
+  #   write to `consumed` is safely picked up on the next call because
+  #   `consumed += diff` accumulates rather than overwriting.
+  # - MRI serializes trap handlers and runs them at safepoints — no
+  #   two handlers execute concurrently, and `@x += 1` in a trap is
+  #   atomic with respect to the main thread (the main thread is
+  #   paused while the trap runs). On JRuby/TruffleRuby, additional
+  #   memory fences may be needed; this class targets MRI only for the
+  #   Bootstrap layer. Richer SkillSet coordinators (see
+  #   daemon_runtime §2.7 SignalCoordinator) use pipes + ConditionVariable
+  #   and are runtime-portable.
+  #
+  # Single-consumer invariant (R3 P3, 4.6):
+  # - `consume_reload!` and `consume_diagnostic!` must be called from
+  #   EXACTLY ONE thread. Two concurrent consumers can both read
+  #   `@reload_seen` and `@reload_consumed`, then each accumulate the
+  #   same diff, double-consuming an edge or mis-ordering the `+=`. The
+  #   Bootstrap layer honors this by having only MainLoop#forward_flags
+  #   (a dedicated bridge thread) call these. Writers (trap handlers)
+  #   may be concurrent with the consumer; that case is covered by the
+  #   ticket accumulation semantics above.
+  # - `shutdown_requested` is a one-way latch: trap sets true, nobody
+  #   ever clears it. This asymmetry is deliberate — shutdown does not
+  #   need edge semantics because it is terminal.
+  class SignalHandle
+    def initialize
+      @shutdown_requested   = false
+      @reload_seen          = 0
+      @reload_consumed      = 0
+      @diagnostic_seen      = 0
+      @diagnostic_consumed  = 0
+    end
+
+    # --- setters (called from Signal.trap context) ---
+    def request_shutdown;   @shutdown_requested = true; end
+    def request_reload;     @reload_seen     += 1;      end
+    def request_diagnostic; @diagnostic_seen += 1;      end
+
+    # --- readers (non-consuming) ---
+    def shutdown_requested?;   @shutdown_requested;                   end
+    def reload_requested?;     @reload_seen     > @reload_consumed;   end
+    def diagnostic_requested?; @diagnostic_seen > @diagnostic_consumed; end
+
+    # Edge-safe consume: returns true if at least one signal arrived
+    # since the last consume. Accumulates rather than overwrites, so a
+    # trap firing mid-consume is never lost.
+    def consume_reload!
+      seen = @reload_seen
+      diff = seen - @reload_consumed
+      @reload_consumed += diff
+      diff.positive?
+    end
+
+    def consume_diagnostic!
+      seen = @diagnostic_seen
+      diff = seen - @diagnostic_consumed
+      @diagnostic_consumed += diff
+      diff.positive?
+    end
+  end
+end

data/lib/kairos_mcp/skillset.rb

@@ -70,6 +70,19 @@ module KairosMcp
       @metadata['tool_classes'] || []
     end
 
+    # 24/7 v0.4 §2.3 — LifecycleHook declarations.
+    # Returns a Hash of { hook_name(String) => class_name(String) }.
+    # Non-Hash values and entries with non-string values are coerced away
+    # so downstream registration never encounters malformed input.
+    def lifecycle_hooks
+      raw = @metadata['lifecycle_hooks'] || {}
+      return {} unless raw.is_a?(Hash)
+      raw.each_with_object({}) do |(k, v), acc|
+        next unless k.is_a?(String) && v.is_a?(String) && !k.empty? && !v.empty?
+        acc[k] = v
+      end
+    end
+
     def config_files
       @metadata['config_files'] || []
     end

data/lib/kairos_mcp/tool_registry.rb

@@ -1,6 +1,7 @@
 require_relative 'safety'
 require_relative 'tools/base_tool'
 require_relative 'skills_config'
+require_relative 'lifecycle_hook'
 
 module KairosMcp
   class ToolRegistry
@@ -50,9 +51,135 @@ module KairosMcp
       @safety = Safety.new
       @safety.set_user(user_context) if user_context
       @tools = {}
+      @lifecycle_hooks = {}  # { hook_name(Symbol) => { skillset:, class_name: } }
       register_tools
     end
 
+    # 24/7 v0.4 §2.3 — LifecycleHook registry.
+    #
+    # Register a hook declaration from a SkillSet. Conflicts (same hook
+    # name claimed by two SkillSets) raise LifecycleHook::Conflict — the
+    # Bootstrap layer refuses to silently pick a winner.
+    def register_lifecycle_hook(hook_name, class_name, skillset_name:)
+      key = hook_name.to_sym
+      # R1 P1 (2-voice security): validate class name + enforce namespace
+      # allowlist before trusting any skillset-sourced class identifier.
+      validated = LifecycleHook.validate_class_name!(class_name)
+
+      existing = @lifecycle_hooks[key]
+      if existing && existing[:skillset] != skillset_name
+        raise LifecycleHook::Conflict,
+              "LifecycleHook '#{hook_name}' claimed by both " \
+              "'#{existing[:skillset]}' and '#{skillset_name}'"
+      end
+      # R1 P2 (3-voice): same-skillset re-registration must not silently
+      # overwrite with a DIFFERENT class. Same-class re-registration is a
+      # harmless idempotent load (tests, reload).
+      if existing && existing[:class_name] != validated
+        raise LifecycleHook::Conflict,
+              "LifecycleHook '#{hook_name}' re-registered by " \
+              "'#{skillset_name}' with different class " \
+              "('#{existing[:class_name]}' → '#{validated}')"
+      end
+      @lifecycle_hooks[key] = { skillset: skillset_name, class_name: validated }
+    end
+
+    # Resolve a registered hook to its Class (without instantiating).
+    # Returns nil if no SkillSet declared the hook. Raises
+    # `LifecycleHook::UnknownClass` if the registered class name cannot
+    # be constantized or does not include `LifecycleHook`.
+    #
+    # R8→R9 (3-voice: Codex P1 / 4.6 P2 / 4.7 P2): split class-resolution
+    # from instantiation so bin/ can `.new` under a precise rescue. The
+    # broad `rescue StandardError` in the entrypoint otherwise mislabels
+    # any registry-logic bug as an instantiation failure.
+    def lifecycle_hook_class(hook_name)
+      entry = @lifecycle_hooks[hook_name.to_sym]
+      return nil unless entry
+      begin
+        klass = Object.const_get(entry[:class_name])
+      rescue NameError => e
+        raise LifecycleHook::UnknownClass,
+              "lifecycle hook class '#{entry[:class_name]}' is not defined " \
+              "(declared by '#{entry[:skillset]}'): #{e.message}"
+      end
+      unless klass.is_a?(Class) && klass.include?(KairosMcp::LifecycleHook)
+        raise LifecycleHook::UnknownClass,
+              "class '#{entry[:class_name]}' does not include KairosMcp::LifecycleHook"
+      end
+      klass
+    end
+
+    # Instantiate a pre-resolved lifecycle hook class and verify the
+    # resulting instance actually includes LifecycleHook (guards against
+    # pathological `.new` overrides that return unrelated objects).
+    #
+    # Raises `LifecycleHook::InstanceViolation` if `.new` returns the
+    # wrong type (a distinct contract violation, separate from lookup
+    # failures that raise UnknownClass). Any other error from `.new`
+    # propagates unchanged so the caller's rescue stays precise.
+    #
+    # R9→R10 (Codex P1 / 4.6 P2): shared helper so both `find_lifecycle_hook`
+    # and bin/ get the same pathological-return guard.
+    # R10→R11 (Codex P1 / 4.6 P3 / 4.7 P3): distinct exception class for
+    # wrong-type returns — UnknownClass is semantically wrong here (the
+    # class IS known; it violates the contract at instantiation).
+    # R12→R13: `.new` return values may be arbitrary — including
+    # `BasicObject` descendants that don't respond to `.class`, `.is_a?`,
+    # or `.inspect`. Use `Module#===` for the type check (works on
+    # BasicObject) and `Object.instance_method(:…).bind_call(obj)` with
+    # rescue-everything fallbacks for error-message formatting.
+    KERNEL_CLASS  = Object.instance_method(:class).freeze
+    KERNEL_INSPECT = Object.instance_method(:inspect).freeze
+    private_constant :KERNEL_CLASS, :KERNEL_INSPECT
+
+    def instantiate_lifecycle_hook(klass)
+      instance = klass.new
+      # `KairosMcp::LifecycleHook === instance` uses Module#=== — does
+      # not call any method on `instance`, so it works on BasicObject.
+      unless KairosMcp::LifecycleHook === instance
+        class_label =
+          (klass.name && !klass.name.empty?) ? klass.name : klass.inspect
+        raise LifecycleHook::InstanceViolation,
+              "#{class_label}.new returned #{safe_inspect(instance)} " \
+              "(#{safe_class_name(instance)}) which does not include " \
+              'KairosMcp::LifecycleHook'
+      end
+      instance
+    end
+
+    # Safely render the class of an arbitrary object — including
+    # BasicObject descendants — without calling methods that may be
+    # missing on the object.
+    def safe_class_name(obj)
+      KERNEL_CLASS.bind_call(obj).to_s
+    rescue Exception # rubocop:disable Lint/RescueException
+      '<class unavailable>'
+    end
+    private :safe_class_name
+
+    # Safe .inspect — tolerates pathological objects whose inspect or
+    # class is undefined/raises.
+    def safe_inspect(obj)
+      KERNEL_INSPECT.bind_call(obj)
+    rescue Exception # rubocop:disable Lint/RescueException
+      "<#{safe_class_name(obj)} (inspect raised)>"
+    end
+    private :safe_inspect
+
+    # Convenience: resolve the class and instantiate. Retained for tests
+    # and callers that do not need to distinguish lookup failures from
+    # constructor failures.
+    def find_lifecycle_hook(hook_name)
+      klass = lifecycle_hook_class(hook_name)
+      return nil unless klass
+      instantiate_lifecycle_hook(klass)
+    end
+
+    def lifecycle_hook_names
+      @lifecycle_hooks.keys
+    end
+
     def register_tools
       # Load all tool files
       Dir[File.join(__dir__, 'tools', '*.rb')].each do |file|
@@ -145,7 +272,13 @@ module KairosMcp
         skillset.tool_class_names.each do |cls|
           register_if_defined(cls)
         end
+        # 24/7 v0.4 §2.3 — register lifecycle hooks declared by this SkillSet.
+        skillset.lifecycle_hooks.each do |hook_name, class_name|
+          register_lifecycle_hook(hook_name, class_name, skillset_name: skillset.name)
+        end
       end
+    rescue LifecycleHook::Conflict
+      raise  # never swallow — Bootstrap integrity depends on detection
     rescue StandardError => e
       warn "[ToolRegistry] Failed to load SkillSet tools: #{e.message}"
     end

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/multi_llm_review_workflow/multi_llm_review_workflow.md

@@ -249,6 +249,97 @@ agent --list-models 2>&1 | grep "(current\|default)"
 # Claude Code: known from session
 ```
 
+### Orchestrator Self-Identification (Self-Referential Model Reporting)
+
+**Rule**: When invoking `multi_llm_review` (or running this workflow manually), the
+orchestrating LLM MUST pass its own model identifier as `orchestrator_model`.
+
+**Rationale**: The reviewer roster typically contains both Opus 4.6 and Opus 4.7
+entries. To avoid the orchestrator reviewing its own output (no independent signal),
+the dispatcher excludes any roster entry whose `model` matches `orchestrator_model`.
+This keeps the same SkillSet useful regardless of which Opus version the user has
+toggled to via `/model` — review composition adapts automatically.
+
+**Why "argument-passing" not "file-introspection"**:
+- The orchestrator's model identity lives in *its own context* (system prompt
+  declares e.g. "You are powered by Opus 4.7"). No external file or env var is
+  authoritative — `/model` switches change context immediately.
+- MCP protocol does not transmit caller-model info; only the orchestrator can
+  truthfully report its own identity. This is genuine self-reference: the system
+  reports its own state to itself.
+- Reading `~/.claude/projects/<cwd>/<sessionId>.jsonl` works but depends on
+  Claude Code internals (format may change between versions). Argument-passing
+  has zero internal-format dependency.
+
+**How orchestrator obtains its model ID**:
+- Claude Code sessions: read the system prompt line "You are powered by the
+  model named ... The exact model ID is `claude-opus-X-Y`". Use the exact ID.
+- Other hosts: use whatever introspection the host provides; if none, pass
+  `null` and accept that no exclusion happens.
+
+**Tool invocation example**:
+```
+multi_llm_review(
+  artifact_path: "log/design.md",
+  review_type: "design",
+  orchestrator_model: "claude-opus-4-7"   # MUST be set by caller
+)
+```
+
+**Dispatcher behavior** (config: `exclude_orchestrator_model: true`, default `true`):
+- If `orchestrator_model` matches a roster entry's `model`, that entry is skipped.
+- `min_quorum` and `convergence_rule` apply to the remaining reviewers.
+- 4-reviewer roster → 3 reviewer; recommended `convergence_rule: "2/3 APPROVE"`
+  when one Opus is excluded.
+- If `orchestrator_model` is `null` or unmatched, full roster runs (back-compat).
+
+**Manual-mode equivalent**: When orchestrating by hand, do not assign yourself
+as a reviewer. Pick the *other* Opus version for the Claude CLI subprocess
+reviewer (4.6 if you are 4.7, and vice versa).
+
+### Orchestrator Delegation Protocol (Two-Phase, opt-in)
+
+The `delegate` strategy lets the orchestrator perform persona-based "Agent Team"
+review in its own context — preserving inherited project context that a fresh
+`claude -p` subprocess loses. Subprocess reviewers (codex, cursor, opposite-Opus)
+remain single-LLM.
+
+**Why**: The orchestrator already holds the artifact in context with full project
+awareness. Re-shipping it to a sandboxed subprocess discards that context. Same-
+model persona switching gives stylistic / framing diversity (validated empirically);
+cross-model subprocess reviewers give epistemic diversity. The two are complementary.
+
+**Call 1**: `multi_llm_review(orchestrator_strategy: "delegate", orchestrator_model: "...")`
+- SkillSet drops the orchestrator-matching reviewer from dispatch
+- Subprocess reviewers run synchronously (no background threads)
+- Subprocess results persisted to `.kairos/multi_llm_review/pending/<uuid>.json`
+- Returns `status: "delegation_pending"`, `collect_token`, `persona_count_min/max`
+
+**Orchestrator's obligation** (between calls):
+- Recognize the `delegation_pending` status
+- Spawn 2-4 parallel `Agent` tool calls with self-chosen personas appropriate to
+  the artifact (e.g. design → architect/security/operability; code → correctness/
+  performance/api-design; doc → ontologist/skeptic/integration)
+- Collect persona results: each as `{persona, verdict (APPROVE|REVISE|REJECT),
+  reasoning, findings: [{severity, issue}, ...]}`
+
+**Call 2**: `multi_llm_review_collect(collect_token, orchestrator_reviews: [...])`
+- Persona Assembly: any REJECT → REJECT; else any REVISE → REVISE; else APPROVE
+- Assembled into one synthetic reviewer entry `claude_team_<orchestrator_model>`
+- Combined with persisted subprocess results, run Consensus, return final verdict
+- Idempotent: repeated calls with the same token return the cached result
+
+**Failure modes**:
+- `expired_or_unknown_token`: orchestrator missed `must_collect_by` deadline
+  (default 600s), or token never existed. The pending review is gone; call
+  `multi_llm_review` again from scratch.
+- `error: invalid orchestrator_reviews`: persona count outside 2-4 or missing
+  required fields. Fix and retry collect with the same token.
+- All-subprocess-failed at Call 1: returns error immediately; no token issued.
+
+**Default**: `orchestrator_strategy` defaults to `"exclude"` (back-compat). Use
+`"delegate"` explicitly until validated by use.
+
 ### Critical CLI Notes
 
 - **Cursor Agent stdin**: `cat file | agent -p -` does NOT work. Use file-reference: