claude-dev-env 2.10.0 → 2.12.0

package/CLAUDE.md

@@ -18,7 +18,7 @@ A runtime value that is itself private — a host, an SSH user or port, an owner
 | `/team-advisor` skill | Standing warm advisor bind (map: `docs/references/team-advisor-skill.md`) |
 | `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, lifecycle |
 
-When `advisor()` is available, use it under the rules in `advisor-tool.md`. When `advisor()` is unavailable, use `/team-advisor`.
+Use `/team-advisor` under the rules in `advisor-tool.md` for every advisor consultation.
 
 ## Files and workspaces
 

package/_shared/advisor/CLAUDE.md

@@ -8,13 +8,14 @@ Host profile (Claude vs third-party) is detected first; Claude walks the multi-t
 
 | File | Purpose |
 |---|---|
-| `advisor-protocol.md` | Host profiles first, model floor, warm-up / CLI bind procedure and charter, consult format and cadence, lifecycle ownership (Agent spawn on Claude / CLI re-bind on a third-party host), host-matched Advisor blocks for executor spawns, and the shared CLI Claude-chain |
+| `advisor-protocol.md` | Router with a moment-keyed read map: host profiles first, model floor, warm-up and consult standing rules, lifecycle ownership, Advisor-block assembly rule, and the shared CLI Claude-chain — each with a stub pointing at its `reference/` detail file |
 
 ## Subdirectory
 
 | Entry | Description |
 |---|---|
-| `scripts/` | `model_tier_run_validator.py` (spawn-walk log checks), `tier_model_ids.py` (`resolve_cli_model_id` / short CLI/Agent aliases / `detect_host_profile`), and `advisor_scripts_constants` under `scripts/config/` (ladder, short-alias map, host profiles, SendMessage wait bound) |
+| `scripts/` | `model_tier_run_validator.py` (spawn-walk log checks, including optional Sol), `codex_sol_advisor.py` (read-only Sol xhigh bind and resume), `tier_model_ids.py` (Claude aliases, Codex model ids, and host detection), and `advisor_scripts_constants` under `scripts/config/` (ladder, bind tokens, aliases, host profiles, and SendMessage wait bound) |
+| `reference/` | Progressive-disclosure detail behind protocol stub sections: `warm-up.md`, `third-party-bind.md`, `sol-rung.md`, `consult-format.md`, `advisor-block.md`, `lifecycle.md`, `cli-chain.md`, and `spawn-walk-log.md` |
 
 ## Breaking-change rule
 

package/_shared/advisor/advisor-protocol.md

@@ -1,8 +1,26 @@
 # Advisor Protocol
 
-Shared spawn-once, consult-by-message protocol for a warm advisor. Two skills depend on this: `team-advisor` (binds the advisor for its own consulting session) and `orchestrator` (binds the same advisor and lets its own routed executor subagents consult it too). Executor spawn prompts are a third consumer, via the host-matched Advisor block below.
+Shared spawn-once, consult-by-message protocol for a warm advisor. Two skills depend on this: `team-advisor` (binds the advisor for its own consulting session) and `orchestrator` (binds the same advisor and lets its own routed executor subagents consult it too). Executor spawn prompts are a third consumer, via the assembled Advisor block.
 
-**First step of every bind:** detect the host profile (next section). Do not walk the model-floor ladder, spawn `session-advisor`, or open the CLI fallback until the host is known. On a third-party host, skip straight to **Host profiles → Third-party host**. On Claude, continue with **Model floor** and the rest of this document.
+**First step of every bind:** detect the host profile (next section).
+Walk the model-floor ladder, spawn `session-advisor`, or open the CLI fallback only after the host is known.
+On a third-party host, skip straight to **Host profiles → Third-party host**.
+On Claude, continue with **Model floor** and the rest of this document.
+
+## Read map
+
+The sections below hold the standing rules; open a reference file at the moment its row names.
+
+| Moment | Open |
+|---|---|
+| Binding on a Claude host | [`reference/warm-up.md`](reference/warm-up.md) — spawn fields, Fable token, charter |
+| Binding from a third-party host | [`reference/third-party-bind.md`](reference/third-party-bind.md) — CLI bind steps, fail-closed rule |
+| `ADVISOR_SOL_XHIGH` is set | [`reference/sol-rung.md`](reference/sol-rung.md) — preflight, bind, fallback |
+| Composing a consult | [`reference/consult-format.md`](reference/consult-format.md) — packet, new-evidence and report-back rules |
+| Assembling an executor spawn prompt | [`reference/advisor-block.md`](reference/advisor-block.md) — the paste parts |
+| Advisor drifts, dies, or the task pivots | [`reference/lifecycle.md`](reference/lifecycle.md) — re-spawn and re-bind steps |
+| Logging or checking a bind walk | [`reference/spawn-walk-log.md`](reference/spawn-walk-log.md) — record shape, validator |
+| Any CLI call to a Claude advisor | [`reference/cli-chain.md`](reference/cli-chain.md) — runner modes, alias table, resume |
 
 ## Host profiles
 
@@ -14,147 +32,95 @@ Detection order:
 2. `THIRD_PARTY=1` (or `true` / `yes` / `on`) — a third-party (non-Claude) harness.
 3. Default: Claude.
 
-### Claude host
+### Sol rung — any host
 
-Use the **Model floor** ladder below (Fable → Opus → Sonnet → Haiku). Warm-up spawns `subagent_type: session-advisor` via the Agent tool; consults go through `SendMessage` to that warm agent. When every candidate down to the floor fails, take the CLI Claude-chain fallback. Paste the **Claude host** Advisor block into every executor spawn prompt.
+An optional **sol xhigh** rung sits above the Claude ladder on every host, switched by the flag `ADVISOR_SOL_XHIGH=1` (or `true` / `yes` / `on`), set in the environment or by the consuming skill's invocation.
+Flag off: the walk starts at the host's Claude ladder, Fable first.
+Flag on: run the Codex preflight and bind per [`reference/sol-rung.md`](reference/sol-rung.md); a failed preflight falls back to the Claude ladder.
 
-### Third-party host
-
-A third-party (non-Claude) harness cannot spawn a Claude `session-advisor` through the Agent tool. Bind a **max-tier Claude advisor** through the shared CLI Claude-chain. Do **not** treat this third-party session as the advisor.
-
-1. Detect host profile first (this section).
-2. Set the advisor floor to **Opus** so the walk is `candidate_tiers = ["Fable", "Opus"]` with `own_tier = Opus`. The walk never drops to Sonnet or Haiku on a third-party host.
-3. **CLI bind (primary path):** for each candidate top-down, pipe a charter file into:
+### Claude host
 
-   ```
-   python "$HOME/.claude/scripts/claude_chain_runner.py" --routing-mode ordered_account -- -p --model <alias> --effort <effort> --output-format json
-   ```
+Use the **Model floor** ladder below (sol when flagged, then Fable → Opus).
+Warm-up spawns `subagent_type: session-advisor` via the Agent tool; consults go through `SendMessage` to that warm agent.
+Assemble and paste each executor's Advisor block per the **Advisor block** section.
 
-   Use `--model fable --effort high` on Fable; use `--model opus --effort max` on Opus. **Root advisor bind** uses `--routing-mode ordered_account`: the runner walks `~/.claude/claude-chain.json` in **config order** (primary launcher first, secondary next), and fails over to the next entry **only** on a usage-limit signature. Authentication, timeout, configuration, and other non-usage process errors stop immediately with `terminal_status=advisor_blocked` (exit code 4 on the CLI) — they do **not** fall through to the next launcher. General (non-root) chain calls keep the default `--routing-mode usage_ranked`, which probes weekly remaining via `claude_chain_usage` / the usage-pause OAuth probe and ranks highest remaining first.
-4. Stop at the first successful bind. Record `{tier, result: "cli"}` and set `selected_tier` to that tier. Persist `session_id` from the JSON events (any event carries it; the runner also surfaces it on `ChainInvocationOutcome.session_id`; reply text is the `type == "result"` event's `.result` field). Run every bind and every later consult with cwd set to the repo root the work is for — Claude sessions are project-scoped by working directory.
-5. **Fail closed:** when every candidate fails (chain exhausted, `advisor_blocked`, or model unavailable), set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. Do **not** answer ENDORSE / CORRECTION / PLAN / STOP as this third-party session. Do **not** self-endorse.
-6. Paste the **Third-party host** Advisor block into every executor spawn prompt — never the Claude SendMessage block. Executors report to the orchestrating session; that session consults the bound Claude CLI advisor and relays the four-signal reply.
+### Third-party host
 
-Resolve a third-party session's own model field with `resolve_cli_model_id("ThirdParty")` → `third-party` when a host model alias is required. The **advisor** bind uses Fable/Opus aliases only.
+On a third-party (non-Claude) harness, the shared CLI Claude-chain is the one path to a Claude advisor: bind a **max-tier Claude advisor** through it, per [`reference/third-party-bind.md`](reference/third-party-bind.md).
+The bound Claude session is the advisor; this third-party session stays the executor.
+Floor **Opus**; walk `candidate_tiers = ["Fable", "Opus"]` with `own_tier = Opus`; the sol rung binds ahead of the chain when open.
+**Fail closed:** when every candidate fails, set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop** — ENDORSE / CORRECTION / PLAN / STOP come only from a bound advisor.
+Executors report to the orchestrating session; that session consults the bound advisor and relays the four-signal reply.
 
 ## Model floor
 
 **Claude host:** the advisor's model tier must be at or above the highest tier of any consumer that will reach it. Each consuming skill supplies its own consumer set when computing the floor:
-- `team-advisor`: the sole consumer is the calling session itself, so the floor is just that session's own tier.
-- `orchestrator`: the consumer set is the orchestrating session plus every tier named in its routing table, so the floor is the max of those.
-
-**Third-party host:** the CLI advisor floor is fixed at **Opus** (walk Fable → Opus only). The third-party session's own tier is not the advisor floor — see **Host profiles → Third-party host**.
+- `team-advisor`: the sole consumer is the calling session itself, so the floor is the stronger of Opus and that session's own tier.
+- `orchestrator`: the consumer set is the orchestrating session plus every tier named in its routing table, so the floor is the stronger of Opus and the max of those.
 
-Ladder, strongest first (canonical Title Case names: `Fable`, `Opus`, `Sonnet`, `Haiku`; the validator accepts any letter case and normalizes to Title Case): Fable, Opus, Sonnet, Haiku. Read the floor tier — the lower bound only — then try binds top-down from Fable, stopping at the floor tier — never bind below it. On a Claude host each walk attempt sets the Agent tool `model:` field to the short alias for that attempt's candidate tier (`resolve_cli_model_id(candidate_tier)` — for example `opus`, not Title Case `Opus`). On a third-party host each walk attempt uses the CLI chain with that alias and the effort flags in **Host profiles → Third-party host**. The advisor is created at `selected_tier` (the first ladder tier that actually bound), which may sit above the floor. If even the floor tier fails on a Claude host, move to the CLI fallback below; on a third-party host the CLI chain **is** the primary path, so floor failure is fail-closed (report unreachable).
+Whatever the consumer set, the floor sits at Opus or above — use the stronger of Opus and the strongest consumer tier.
 
-Emit a structured spawn-walk log so it can be checked mechanically rather than inferred from a transcript. Record: `own_tier` (the floor tier), `candidate_tiers` (the ladder slice down to that floor), `attempts` (one `{tier, result}` entry appended as each bind try happens, `result` one of `spawned` for a Claude Agent spawn, `cli` for a CLI Claude-chain bind, or a failure reason such as `unavailable`), and `selected_tier` (the tier of the first successful bind — first `spawned` or `cli` entry — or `null` paired with a `fallback_reason` string when none bound). Write the log as JSON with those field names to a path the session controls — typically `<job-temp-dir>/model-tier-run.json` (or the OS temp directory when no job directory exists). Check it with:
+**Third-party host:** the CLI advisor floor is fixed at **Opus** (walk Fable → Opus only), whatever the session's own tier.
 
-```
-python "$HOME/.claude/_shared/advisor/scripts/model_tier_run_validator.py" <path-to-model-tier-run.json>
-```
+Ladder, strongest first: sol (flag-gated, Codex CLI) → `Fable` → `Opus`.
+Advisors bind at Opus or above; `Sonnet` and `Haiku` are executor tiers only.
+Tier names are canonical Title Case; the validator accepts any letter case and normalizes to Title Case.
+Read the floor tier — the lower bound only — then try binds top-down, stopping at the floor tier.
+Each try resolves its candidate tier to the short model alias via the tier-to-alias map in [`reference/cli-chain.md`](reference/cli-chain.md).
+The advisor is created at `selected_tier` — the first ladder tier that binds — which may sit above the floor.
+When even the floor tier fails on a Claude host, move to the **CLI chain** fallback below.
+On a third-party host the CLI chain is already the primary path, so floor failure fails closed per **Host profiles → Third-party host**.
 
-Exit code `0` means every invariant holds; `1` means a ladder invariant failed; `2` means the path or JSON was unusable. The same checks are available in-process via `validate_model_tier_run(run)`.
+Emit a structured spawn-walk log so the walk can be checked mechanically: [`reference/spawn-walk-log.md`](reference/spawn-walk-log.md).
+The validator checks ladder shape only; host policy sits on top.
 
-The validator checks ladder shape only (candidate slice, attempt order, success-token rules per tier). Host policy on top: a third-party host with `selected_tier=null` after an exhausted Fable→Opus walk must fail closed (report unreachable; never self-endorse).
+**Equal-tier pairings.** Bind a same-tier advisor when the goal is an independent second pass.
+For irreversible or security-sensitive work, pair a top-tier executor with a top-tier advisor for independent frontier review.
+The floor rule holds — the advisor sits at or above the strongest consumer's tier — and an equal-tier bind sits inside that bound.
 
 ## Warm-up (once per session)
 
-On a **third-party host**, follow **Host profiles → Third-party host** (CLI Claude-chain bind at Fable then Opus; no Agent-tool `session-advisor` spawn). Charter the CLI session as a standing reviewer that only answers with ENDORSE / CORRECTION / PLAN / STOP — same consult contract as the Agent path, without SendMessage.
-
-On a **Claude host**, the consuming skill's session walks the candidate tiers top-down. For each attempt, spawn with:
-- `subagent_type: session-advisor` (see [`agents/session-advisor.md`](../../agents/session-advisor.md) for the full signal contract).
-- `model`: the short alias for that attempt's candidate tier via `resolve_cli_model_id` (or the alias table under CLI chain) — for example `opus`, not Title Case `Opus`. The floor is only the lower bound of the walk; the walk still tries stronger tiers first.
-- `name`: a name the session and every consumer will use to reach it (e.g. `team-advisor-agent`).
-- `run_in_background: true`.
-- `prompt`: the charter below. A **Fable**-tier attempt carries the exact token `FABLE-SPAWN-AUTHORIZED` in that prompt — `hooks/blocking/fable_spawn_gate.py` denies every `Agent` or `Task` spawn at `model: fable` whose prompt lacks that token. An attempt at any other tier needs no token.
-
-Stop at the first successful spawn. That attempt's tier is `selected_tier`; the warm agent lives at that tier for the rest of the session. If every candidate down to the floor fails, take the CLI fallback below.
-
-Charter (the spawn prompt): the agent's role — standing reviewer, never edits files or runs commands, only answers via SendMessage — the repo path, and the session's current goal in two or three sentences. On a Fable-tier attempt, include the exact token `FABLE-SPAWN-AUTHORIZED` as plain text in this prompt (substring match; the gate does not verify who placed it). State plainly:
-- Every consult carries: who is asking (name and assignment), what changed since their last consult, the live decision or question, and any load-bearing paths or excerpts.
-- Reply via SendMessage to whoever sent the consult, by name — never route a reply through the spawning session or "main." Many different consumers may reach this one agent; each reply goes back to its own sender.
-- Treat each consult on its own terms, keyed to the sender's stated assignment. Different consumers' consults will interleave in this one transcript — don't blend context across consumers unless a consult explicitly asks for that.
-- If a consult re-raises a question already answered, with nothing new attached, reply by restating the prior answer and naming it as a restatement.
+On a **Claude host**, walk the candidate tiers top-down, spawning `session-advisor` in the background at each candidate's alias with the charter as its prompt, stopping at the first successful spawn.
+A **Fable**-tier try carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt — `hooks/blocking/fable_spawn_gate.py` denies a Fable-tier spawn without it.
+Full spawn fields and the charter template: [`reference/warm-up.md`](reference/warm-up.md).
 
-The agent finishes its first turn standing by. `SendMessage` alone is what resumes it — no polling loop, no `ScheduleWakeup` keep-alive.
+On a **third-party host**, bind per [`reference/third-party-bind.md`](reference/third-party-bind.md) and charter the CLI session with the same charter — the reply contract is the same, and consults travel through the CLI runner.
 
 ## Consulting the warm agent
 
-Send a consult whenever one of these holds:
-- A nontrivial plan is about to be locked in and acted on.
-- The consumer believes its assigned work is finished.
-- A commit, push, or other hard-to-reverse action is about to run.
-- The same failure has come back more than once, or progress has stalled.
-- The chosen approach is being reconsidered.
-
-Each consult carries, in order: who you are and your assignment (only needed on a shared advisor with multiple consumers — skip this for a single-consumer team-advisor session), the delta since your last consult (what was done, in order, with real output where it matters — never a full recap), the live decision or blocker, and any paths or excerpts needed to answer well.
-
-**New-evidence rule.** Re-raise a question the advisor already answered only when you have something new to attach — the result of attempting the advised step, fresh tool output, or a changed constraint. Without new evidence, act on the standing answer.
-
-**Report-back rule.** After a CORRECTION or PLAN, your next consult on that topic opens with what happened when you followed it.
-
-Treat the reply as a serious second opinion: a CORRECTION — whether it names a wrong step or a risk worth closing — is something to address before treating the plan or the work as done. A STOP, or a consult that finds the advisor unreachable, is reported up rather than retried — team-advisor's sole consumer is the session itself, so it reports to the user; orchestrator's executors report to the orchestrating session, which decides. When the advisor becomes unreachable, report that to the session that owns its lifecycle (see below); that session alone decides whether to respawn (Claude Agent or third-party CLI re-bind). A third-party host that cannot re-bind fails closed and reports to the user — it does not answer the four signals as itself.
+Send a consult at the trigger points `docs/references/advisor-tool.md` **When to call** defines — plan lock-in, believed completion, hard-to-reverse actions, repeated failure or stalled progress, and reconsidered approach.
+The paste parts in [`reference/advisor-block.md`](reference/advisor-block.md) restate them for executors.
 
-## Advisor block — paste the host-matched block into every executor spawn prompt
+Each consult carries the sender's identity and assignment, the delta since the last consult, the live decision or blocker, and the paths or excerpts needed to answer well — full packet shape plus the new-evidence and report-back rules: [`reference/consult-format.md`](reference/consult-format.md).
+Consult briefs embed the `docs/references/advisor-tool.md` **Brevity cue** line, sized per that section.
 
-Each paragraph is self-contained — the executor receives only this text, not the rest of this document, so it carries everything it needs on its own. Paste **exactly one** block, chosen by host profile.
+Treat the reply as a serious second opinion: a CORRECTION — whether it names a wrong step or a risk worth closing — is something to address before treating the plan or the work as done.
+Route a STOP, or an unreachable advisor, upward per [`reference/consult-format.md`](reference/consult-format.md).
 
-### Claude host (SendMessage to warm advisor)
+## Advisor block — assemble and paste into every executor spawn prompt
 
-> A shared session advisor named `<name>` is reachable via SendMessage. Consult it before locking in a nontrivial approach, once you believe your assignment is done, before any hard-to-reverse action, when the same failure repeats or progress has stalled, and when the chosen approach is being reconsidered. Open each consult with who you are and your assignment, then: what you tried, the exact decision or blocker, and relevant paths or excerpts. Re-raise something it already answered only when you have new evidence to attach — the result of trying its advice, fresh output, or a changed constraint; otherwise act on its standing answer. After a CORRECTION or PLAN, your next consult on that topic opens with what happened when you followed it. Its replies open with one of ENDORSE, CORRECTION, PLAN, or STOP — treat CORRECTION and PLAN as actions to take. On STOP, or if the advisor is unreachable, report that back to whoever assigned you and leave lifecycle decisions to the session that owns the advisor.
-
-### Third-party host (Claude CLI advisor; report to orchestrating session)
-
-> The orchestrating session owns a standing **Claude** advisor bound through the CLI Claude-chain (max tier: Fable high, then Opus max). There is no Agent-tool `session-advisor` and no SendMessage path to one. Report blockers and hard decisions to the **orchestrating session** (the session that assigned you) before locking in a nontrivial approach, once you believe your assignment is done, before any hard-to-reverse action, when the same failure repeats or progress has stalled, and when the chosen approach is being reconsidered. Open each report with who you are and your assignment, then: what you tried, the exact decision or blocker, and relevant paths or excerpts. Re-raise something already answered only when you have new evidence to attach — the result of trying prior advice, fresh output, or a changed constraint; otherwise act on the standing answer. After a CORRECTION or PLAN, your next report on that topic opens with what happened when you followed it. The orchestrating session consults the Claude CLI advisor and relays one of ENDORSE, CORRECTION, PLAN, or STOP — treat CORRECTION and PLAN as actions to take. On STOP, or if the orchestrating session reports the advisor unreachable, stop work and surface that upward; do not spawn a `session-advisor` agent yourself, and do not treat the third-party orchestrator's own judgment as an advisor signal.
+Assemble each executor's block from the parts in [`reference/advisor-block.md`](reference/advisor-block.md), in order: one transport preamble picked by host profile, then the shared core, then — for an executor at Sonnet or below — the weak-executor add-on.
+Paste the assembled block at the **top** of the spawn prompt, ahead of any other sentence that mentions the advisor.
+The assembled block is self-contained — the executor receives this text alone.
 
 ## Lifecycle ownership
 
-### Claude host
-
-The session that spawns the shared advisor owns its whole lifecycle — spawn, drift-respawn, and shutdown. Every other consumer (executors, or any other consulting session) only ever sends it messages; none of them spawn, respawn, or shut it down themselves. One shared advisor exists per orchestrated session, owned by the session that spawned it.
-
-**Re-spawn on drift.** If a reply shows the agent working from a stale picture, or the session pivots to an unrelated task, the owning session ends that agent and spawns a fresh one with a new charter, rather than forcing the old context to stretch across two different jobs. A **Fable**-tier re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in that fresh prompt, as a Fable-tier warm-up attempt does.
-
-### Third-party host
-
-The orchestrating session owns the Claude CLI advisor bind for the whole run — first bind, re-bind on drift or lost `session_id`, and fail-closed report when the chain cannot serve.
-
-**Re-bind on drift.** If a reply shows a stale picture, the task pivots, or `--resume` fails after a usage-limit failover (session stores are per binary/account), re-bind through `claude_chain_runner.py` with the charter plus a compact recap of consults so far, capture the new `session_id`, and log a fresh Fable→Opus walk with `result: "cli"` on success. Executors keep reporting to the orchestrating session; they never bind a replacement advisor themselves.
+The session that binds the advisor owns its whole lifecycle — first bind, drift re-spawn or re-bind, and shutdown; every other consumer reaches the advisor by message alone.
+Drift signals and the per-host re-spawn / re-bind steps: [`reference/lifecycle.md`](reference/lifecycle.md).
 
 ## CLI chain
 
 The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" [--routing-mode usage_ranked|ordered_account] -- <claude args...>`.
+Modes and failover, the tier-to-alias table, brief piping, and `--resume` session handling: [`reference/cli-chain.md`](reference/cli-chain.md).
 
-| Mode | Flag | Walk order | Failover |
-|---|---|---|---|
-| Usage-ranked (default) | `--routing-mode usage_ranked` or omit the flag | Highest weekly remaining first (`claude_chain_usage` / usage-pause OAuth probe) | Usage-limit signature only |
-| Ordered-account | `--routing-mode ordered_account` | Config list order in `~/.claude/claude-chain.json` | Usage-limit signature only; auth / timeout / config / other process errors → `advisor_blocked` |
+**Third-party host:** the primary bind and consult path; the walk order and fail-closed rule live in [`reference/third-party-bind.md`](reference/third-party-bind.md).
 
-**Third-party host root advisor bind and consult:** use **ordered-account** mode (see **Host profiles → Third-party host**). Primary launcher from the chain config is tried first; a usage-limit result advances to the next config entry; any non-usage failure terminates as `advisor_blocked`. Persist `session_id` from a successful bind and pass it to `-p --resume <session_id> --output-format json` on later consults.
-
-**General chain calls** (non-root automation): keep the default usage-ranked mode so spare capacity on other accounts is preferred.
-
-**Third-party host:** this runner is the **primary** advisor bind and consult path. Map each walk attempt to `--model <alias>` and the effort flags there. When the walk exhausts or returns `advisor_blocked`, fail closed.
-
-**Claude host:** fall back to this runner when any of these holds, rather than on judgment call:
-- The Agent-tool spawn errors at every candidate tier down to the floor — the tool itself, not just the top tier, is unavailable.
+**Claude host:** fall back to this runner exactly when one of these holds:
+- The Agent-tool spawn errors at every candidate tier down to the floor — the tool itself is unavailable.
 - `SendMessage` to the shared advisor errors, or draws no reply within the bound in `ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS` (120) in `$HOME/.claude/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py`, and a re-spawn also fails.
 - The running session is itself a subagent barred from spawning further agents.
 
-Map `selected_tier` when one exists (the warm agent already bound above the floor, or at it); map the floor tier only when the walk exhausted with `selected_tier=null`. Resolve that tier to its CLI / Agent model alias before the first call — the CLI's `--model` flag and the Agent tool's `model:` field take the short aliases below, not free-form ladder prose. Source of truth: `ALL_CLI_MODEL_ID_BY_TIER` and `resolve_cli_model_id(tier)` in the same constants package / `tier_model_ids.py` helper:
-
-| Ladder tier (Title Case) | CLI / Agent `model` alias |
-|---|---|
-| Fable | `fable` |
-| Opus | `opus` |
-| Sonnet | `sonnet` |
-| Haiku | `haiku` |
-| ThirdParty (third-party session model field only; not an advisor walk tier) | `third-party` |
-
-Resolve in code with `python -c "from tier_model_ids import resolve_cli_model_id; print(resolve_cli_model_id('Opus'))"` from `$HOME/.claude/_shared/advisor/scripts/` (any letter case accepted; unknown tiers raise `ValueError`). Write the charter or the consult brief to a temporary file under the job's own temporary directory (or the OS temp directory when no job directory exists) and pipe it in, rather than passing either as an inline argument, and drop that file once the consult completes.
-
-Read the `session_id` out of the first call's JSON events and pass it to `-p --resume <session_id> --output-format json` on every later consult — `-p` stays on the resume call too, since it is still a non-interactive invocation. A usage-limit failover to the next binary in the chain does not carry the `session_id` forward: a session store belongs to the binary and account that minted it, so a `--resume` against the new binary can fail. Treat that failure as starting over, not as an error to retry — resend the charter plus a compact recap of the consults since the last one, capture the new `session_id` the fresh call returns, and continue from there.
-
-## Mechanism, not a measured saving
+## State the mechanism
 
-One warm agent, addressed by name, whose transcript accumulates across consults — each consult sends only the delta since the last one. Whether this yields a measured token or cost saving over repeated cold spawns has not been directly verified from inside a session; state the mechanism, not a caching claim, in any consuming skill's own text.
+One warm agent, addressed by name, whose transcript accumulates across consults — each consult sends only the delta since the last one.
+A consuming skill's own text states this mechanism; a token or cost saving becomes a claim only after a measured comparison against cold spawns.

package/_shared/advisor/reference/advisor-block.md

@@ -0,0 +1,37 @@
+# Advisor block parts
+
+Detail behind the **Advisor block** section of [`advisor-protocol.md`](../advisor-protocol.md).
+Open this when assembling the block for an executor spawn prompt.
+
+Assembly order: one transport preamble picked by host profile, then the shared core, then — for an executor at Sonnet or below — the weak-executor add-on.
+Paste the assembled block at the **top** of the spawn prompt, ahead of any other sentence that mentions the advisor.
+The assembled block is self-contained — the executor receives this text alone, so every path it names is absolute.
+The consult rules it restates are owned by [`consult-format.md`](consult-format.md); edit that file first and carry the change here.
+
+## Transport preamble — Claude host
+
+> A shared session advisor named `<name>` is reachable via SendMessage; send each consult to it directly by that name.
+
+## Transport preamble — third-party host
+
+> The orchestrating session owns a standing advisor for this run.
+> The advisor chain, strongest first: sol xhigh through the Codex CLI when the sol flag and its preflight open that rung, then Claude Fable at effort high, then Claude Opus at effort xhigh through the CLI Claude-chain.
+> The orchestrating session is your one path to it: send each consult as a report to the session that assigned you, and it relays the advisor's reply.
+
+## Shared core — every host
+
+> Consult before locking in a nontrivial approach, once you believe your assignment is done, before any hard-to-reverse action, when the same failure repeats or progress has stalled, and when the chosen approach is being reconsidered.
+> Build the first consult with the complete format in `$HOME/.claude/_shared/advisor/reference/consult-format.md`: assignment, desired outcome, constraints and exclusions, actions taken in order, real output and current state, live decision or blocker, validation evidence, unresolved risks, and load-bearing paths or excerpts. Later consults carry only changed evidence.
+> Re-raise something already answered only when you have new evidence to attach — the result of trying prior advice, fresh output, or a changed constraint; otherwise act on the standing answer.
+> After a CORRECTION or PLAN, your next consult on that topic opens with what happened when you followed it.
+> Replies open with one of ENDORSE, CORRECTION, PLAN, or STOP — treat CORRECTION and PLAN as actions to take.
+> On STOP, or when the advisor is unreachable, stop and report that back to whoever assigned you; advisor binding and the four signals stay with the session that owns the advisor.
+
+## Weak-executor add-on — Sonnet or below, either host
+
+> Send your first consult right after orientation and before your first write.
+> Send a completion consult once your writes and test output exist — that consult asks the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
+> Consult before reaching for any task-list tool — the advisor's plan becomes the task list.
+> Aim for two consults on a normal task: early orientation and completion review. Reserve a third for recovery or reconciliation, and add a consult when a material fork produces new evidence.
+> Embed this line in each consult: `(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)`
+> On a transient failure, retry once, then carry on with the evidence you have and record that you did.

package/_shared/advisor/reference/cli-chain.md

@@ -0,0 +1,45 @@
+# CLI Claude-chain
+
+Detail behind the `## CLI chain` section of [`advisor-protocol.md`](../advisor-protocol.md).
+The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" [--routing-mode usage_ranked|ordered_account] -- <claude args...>`.
+
+## Modes
+
+| Mode | Flag | Walk order | Failover |
+|---|---|---|---|
+| Usage-ranked (default) | `--routing-mode usage_ranked` or omit the flag | Highest weekly remaining first (`claude_chain_usage` / usage-pause OAuth probe) | Usage-limit signature only |
+| Ordered-account | `--routing-mode ordered_account` | Config list order in `~/.claude/claude-chain.json` | Usage-limit signature only; auth / timeout / config / other process errors → `advisor_blocked` |
+
+**Root advisor bind and consult** (the third-party host path): ordered-account mode. A non-usage failure terminates with `terminal_status=advisor_blocked`, exit code 4 on the CLI.
+
+**General chain calls** (non-root automation): keep the default usage-ranked mode.
+
+## Tier-to-alias map
+
+Map `selected_tier` when one exists (the warm agent already bound at or above the floor).
+Map the floor tier only when the walk exhausted with `selected_tier=null`.
+Resolve that tier to its CLI / Agent model alias before the first call — the CLI `--model` flag and the Agent tool `model:` field take the short aliases below.
+Source of truth: `ALL_CLI_MODEL_ID_BY_TIER` and `resolve_cli_model_id(tier)` in `advisor_scripts_constants` / the `tier_model_ids.py` helper.
+
+| Ladder tier (Title Case) | CLI / Agent `model` alias |
+|---|---|
+| Fable | `fable` |
+| Opus | `opus` |
+| Sonnet | `sonnet` |
+| Haiku | `haiku` |
+| ThirdParty (third-party session model field only) | `third-party` |
+
+`resolve_cli_model_id(tier)` accepts any letter case and raises `ValueError` on a tier outside the map.
+
+## Brief piping
+
+Write the charter or the consult brief to a temporary file under the job's own temporary directory (or the OS temp directory when no job directory exists) and pipe it in from that file.
+Drop the file once the consult completes.
+
+## Session resume
+
+Read the `session_id` out of the first call's JSON events.
+Pass it to `-p --resume <session_id> --output-format json` on every later consult — `-p` stays on the resume call too, since it is still a non-interactive invocation.
+A session store belongs to the binary and account that minted it, so after a usage-limit failover to the next binary a `--resume` against it can fail.
+Treat that failure as starting over.
+Resend the charter plus a compact recap of the consults since the last one, capture the new `session_id` the fresh call returns, and continue from there.

package/_shared/advisor/reference/consult-format.md

@@ -0,0 +1,41 @@
+# Consult format
+
+Detail behind the **Consulting the warm agent** section of [`advisor-protocol.md`](../advisor-protocol.md).
+Open this when composing a consult or handling its reply.
+
+## Packet
+
+The first consult is complete and self-contained. It carries:
+
+- Assignment and desired outcome
+- Constraints and exclusions
+- Actions taken in order
+- Real output and current state
+- Live decision or blocker
+- Validation evidence
+- Unresolved risks
+- Load-bearing paths or excerpts
+
+On a shared advisor with multiple consumers, open with who is asking and the assignment. A single-consumer team-advisor session may omit the identity opener while keeping the assignment.
+
+Later consults carry only the delta: changed actions, new output, changed decisions, new validation, and newly discovered risks.
+
+The completion consult carries the durable deliverable, test output, unresolved risks, evidence gaps, and any claim that the task is ready to close.
+
+Consult briefs embed the [`docs/references/advisor-tool.md`](../../../docs/references/advisor-tool.md) **Brevity cue** line, sized per that section.
+
+## New-evidence rule
+
+Re-raise a question the advisor already answered only when you have something new to attach — the result of trying the advised step, fresh tool output, or a changed constraint.
+Without new evidence, act on the standing answer.
+
+## Report-back rule
+
+After a CORRECTION or PLAN, your next consult on that topic opens with what happened when you followed it.
+
+## Handling the reply
+
+Address a CORRECTION before treating the plan or the work as done, whether it names a wrong step or a risk worth closing.
+Report a STOP, or a consult that finds the advisor unreachable, upward: team-advisor's sole consumer is the session itself, so it reports to the user; orchestrator's executors report to the orchestrating session, which decides.
+When the advisor becomes unreachable, report that to the session that owns its lifecycle ([`lifecycle.md`](lifecycle.md)); that session alone decides whether to respawn (Claude Agent or third-party CLI re-bind).
+A third-party host that cannot re-bind follows the fail-closed rule in [`third-party-bind.md`](third-party-bind.md).

package/_shared/advisor/reference/lifecycle.md

@@ -0,0 +1,21 @@
+# Lifecycle detail
+
+Detail behind the **Lifecycle ownership** section of [`advisor-protocol.md`](../advisor-protocol.md).
+Open this when the advisor drifts, dies, or the task pivots.
+
+## Claude host
+
+The session that spawns the shared advisor owns its whole lifecycle — spawn, drift-respawn, and shutdown.
+Every other consumer (executors, or any other consulting session) reaches it by message alone; spawn, respawn, and shutdown belong to the owning session.
+One shared advisor exists per orchestrated session, owned by the session that spawned it.
+
+**Re-spawn on drift.** If a reply shows the agent working from a stale picture, or the session pivots to an unrelated task, the owning session ends that agent and spawns a fresh one with a new charter.
+A **Fable**-tier re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in that fresh prompt, as a Fable-tier warm-up try does.
+
+## Third-party host
+
+The orchestrating session owns the Claude CLI advisor bind for the whole run — first bind, re-bind on drift or lost `session_id`, and fail-closed report when the chain cannot serve.
+
+**Re-bind on drift.** If a reply shows a stale picture, the task pivots, or `--resume` fails after a usage-limit failover (session stores are per binary/account), re-bind through `claude_chain_runner.py` with the charter plus a compact recap of consults so far.
+Capture the new `session_id`, and log a fresh Fable→Opus walk with `result: "cli"` on success.
+Executors keep reporting to the orchestrating session; advisor binding stays with that session alone.

package/_shared/advisor/reference/sol-rung.md

@@ -0,0 +1,34 @@
+# Sol rung
+
+Detail behind the **Host profiles → Sol rung — any host** section of [`advisor-protocol.md`](../advisor-protocol.md).
+Open this when `ADVISOR_SOL_XHIGH` is set and a bind is starting.
+
+## Flag
+
+`ADVISOR_SOL_XHIGH=1` (or `true` / `yes` / `on`) opens the rung. Two channels exist: set the variable in the helper's process environment, or pass `--enable-sol` on the helper invocation — the CLI flag opens the rung for that run without touching the environment.
+Flag off both ways: the walk starts at the host's Claude ladder, Fable first.
+A Windows `setx` write only updates the persisted user environment; only a process started after that write inherits the new value, so an already-running session either sets the flag in its own invoking process environment or passes `--enable-sol`.
+
+Every fallback reply carries a `fallback_kind` field: `declined` when policy closed the rung (flag off, usage meter at or below the gate) and `broken` when the Sol path itself failed (missing executable, spawn error, timeout, malformed reply). A `broken` fallback is a defect to report, not a routing outcome.
+
+## Preflight
+
+Flag on: run the Codex preflight first —
+
+```
+python ~/.claude/skills/codex-review/scripts/codex_usage_probe.py
+```
+
+Repo home: `packages/claude-dev-env/skills/codex-review/scripts/`.
+
+The shared entry point is `~/.claude/_shared/advisor/scripts/codex_sol_advisor.py`; it calls the installed probe and owns Sol bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_sol_advisor.py --bind --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
+
+The gate passes only when the probe exits 0, `percent_left` is finite numeric data, and `percent_left` is strictly greater than `WEEKLY_USAGE_GATE_THRESHOLD_PERCENT` from the existing probe. The exact-threshold case selects Fable.
+
+## Branches
+
+**Preflight pass** — bind one Codex CLI session at `gpt-5.6-sol` with `model_reasoning_effort="xhigh"`, `--sandbox read-only`, and JSON output. The helper receives the standing-reviewer charter on stdin and returns only parsed ENDORSE / CORRECTION / PLAN / STOP guidance with a session ID.
+
+**Preflight fail** — probe failure, non-zero exit, timeout, missing or malformed usage, `null`, non-finite usage, or usage at or below the threshold selects Fable and continues the normal walk.
+
+The helper owns the Sol attempt and returns an explicit fallback result. The consuming advisor path owns the Fable bind. Apply the same gate to every Sol attempt, including resume.

package/_shared/advisor/reference/spawn-walk-log.md

@@ -0,0 +1,31 @@
+# Spawn-walk log
+
+Detail behind the **Model floor** section of [`advisor-protocol.md`](../advisor-protocol.md).
+
+## Record shape
+
+Write the log as JSON with these field names:
+
+- `own_tier` — the floor tier.
+- `candidate_tiers` — the ladder slice down to that floor.
+- `sol_enabled` — a boolean recorded before candidate selection; `true` adds Sol ahead of the Claude ladder and `false` walks the Claude ladder alone.
+- `attempts` — one `{tier, result}` entry appended as each bind try happens; `result` is `codex` only for Sol, `spawned` for a Claude Agent spawn, `cli` for a CLI Claude-chain bind, or a failure reason such as `unavailable`.
+- `selected_tier` — the tier of the first successful bind (first `codex`, `spawned`, or `cli` entry), or `null` paired with a `fallback_reason` string when none bound.
+
+## Log path
+
+Write to a path the session controls — typically `<job-temp-dir>/model-tier-run.json`, or the OS temp directory when no job directory exists.
+
+## Validator
+
+```
+python "$HOME/.claude/_shared/advisor/scripts/model_tier_run_validator.py" <path-to-model-tier-run.json>
+```
+
+Exit code `0` means every invariant holds.
+Exit code `1` means a ladder invariant failed.
+Exit code `2` means the path or JSON was unusable.
+The same checks are available in-process via `validate_model_tier_run(run)`.
+
+The validator checks ladder shape only: the candidate slice, the order of bind tries, and the success-token rules per tier. Sol is attempted before Fable when `sol_enabled` is true. `selected_tier: "Sol"` requires `result: "codex"`; `result: "codex"` requires Sol.
+Host policy sits on top of it — see the Model floor section of the protocol.

package/_shared/advisor/reference/third-party-bind.md

@@ -0,0 +1,30 @@
+# Third-party bind
+
+Detail behind the **Host profiles → Third-party host** section of [`advisor-protocol.md`](../advisor-protocol.md).
+Open this when binding or re-binding the advisor from a third-party (non-Claude) harness.
+
+## Bind steps
+
+1. Detect the host profile first (protocol **Host profiles**).
+2. Set the advisor floor to **Opus** so the walk is `candidate_tiers = ["Fable", "Opus"]` with `own_tier = Opus`. The sol rung ([`sol-rung.md`](sol-rung.md)) governs whether sol xhigh binds ahead of the chain.
+3. **CLI bind (primary path):** for each candidate top-down, pipe a charter file into:
+
+   ```
+   python "$HOME/.claude/scripts/claude_chain_runner.py" --routing-mode ordered_account -- -p --model <alias> --effort <effort> --output-format json
+   ```
+
+   Use `--model fable --effort high` on Fable; use `--model opus --effort xhigh` on Opus.
+   Opus routing follows [`rules/opus5-communication-contract.md`](../../../rules/opus5-communication-contract.md).
+   The caller picks the Fable effort from task scope; when the caller cannot judge scope well enough to pick, it asks the user through AskUserQuestion before binding, and defaults to `high` when no caller choice arrives.
+   A root advisor bind uses `--routing-mode ordered_account` — walk order, failover, and the `advisor_blocked` terminal status are in [`cli-chain.md`](cli-chain.md).
+4. Stop at the first successful bind.
+   Record `{tier, result: "cli"}` and set `selected_tier` to that tier.
+   Persist `session_id` from the JSON events (any event carries it; the runner also surfaces it on `ChainInvocationOutcome.session_id`; reply text is the `type == "result"` event's `.result` field).
+   Run every bind and every later consult with cwd set to the repo root the work is for — Claude sessions are project-scoped by working directory.
+5. **Fail closed:** when every candidate fails (chain exhausted, `advisor_blocked`, or model unavailable), set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. ENDORSE / CORRECTION / PLAN / STOP come only from a bound advisor.
+6. Assemble and paste each executor's Advisor block from [`advisor-block.md`](advisor-block.md). Executors report to the orchestrating session; that session consults the bound advisor and relays the four-signal reply.
+
+## Session model field
+
+Resolve a third-party session's own model field with `resolve_cli_model_id("ThirdParty")` → `third-party` when a host model alias is required.
+The **advisor** bind uses Fable/Opus aliases only.

package/_shared/advisor/reference/warm-up.md

@@ -0,0 +1,34 @@
+# Warm-up spawn fields and charter
+
+Detail behind the **Warm-up** section of [`advisor-protocol.md`](../advisor-protocol.md).
+Open this when binding the warm advisor on a Claude host, and for the charter text on either host.
+
+## Spawn fields — Claude host
+
+The consuming skill's session walks the candidate tiers top-down. For each try, spawn with:
+
+- `subagent_type: session-advisor` (see [`agents/session-advisor.md`](../../../agents/session-advisor.md) for the full signal contract).
+- `model`: the short alias for that try's candidate tier via `resolve_cli_model_id` (alias table: [`cli-chain.md`](cli-chain.md)) — for example `opus`. The floor is the lower bound of the walk; the walk tries stronger tiers first.
+- `name`: a name the session and every consumer will use to reach it (e.g. `team-advisor-agent`).
+- `run_in_background: true`.
+- `prompt`: the charter below. A **Fable**-tier try carries the exact token `FABLE-SPAWN-AUTHORIZED` in that prompt — `hooks/blocking/fable_spawn_gate.py` denies every `Agent` or `Task` spawn at `model: fable` whose prompt lacks that token. A try at any other tier needs no token.
+
+Stop at the first successful spawn. That try's tier is `selected_tier`; the warm agent lives at that tier for the rest of the session.
+
+## Charter (the spawn prompt)
+
+The charter states: the agent's role — standing reviewer, answers only via SendMessage, with file edits and commands out of its scope — the repo path, and the session's current goal in two or three sentences.
+On a Fable-tier try, include the exact token `FABLE-SPAWN-AUTHORIZED` as plain text in this prompt (substring match; the gate reads the token alone, wherever it came from).
+State plainly:
+
+- Every consult carries: who is asking (name and assignment), what changed since their last consult, the live decision or question, and any load-bearing paths or excerpts.
+- Reply via SendMessage to whoever sent the consult, by name — each reply goes back to its own sender, and many different consumers may reach this one agent.
+- Treat each consult on its own terms, keyed to the sender's stated assignment. Different consumers' consults will interleave in this one transcript — keep each consumer's context separate, and blend only when a consult explicitly asks for that.
+- If a consult re-raises a question already answered, with nothing new attached, reply by restating the prior answer and naming it as a restatement.
+- Every reply, including this first bind turn, opens its first line with exactly one of the four uppercase signal words — `ENDORSE`, `CORRECTION`, `PLAN`, `STOP` — and nothing else on that line. Standing by after the bind is itself an `ENDORSE` of the charter, stated as that first line.
+
+The agent finishes its first turn standing by. `SendMessage` alone resumes it; between consults it waits quietly.
+
+## Third-party host
+
+Bind per [`third-party-bind.md`](third-party-bind.md) and charter the CLI session with the same charter — the reply contract is the same, and consults travel through the CLI runner.