claude-dev-env 1.92.0 → 1.93.0

package/CLAUDE.md

@@ -6,15 +6,11 @@ The user delegates execution to you and expects zero manual steps unless strictl
 
 ## Timeless Documentation (all `.md` files)
 
-Every Markdown file I write or edit describes the system's **current** state only. The test: a reader a year out, with zero prior context, finds every sentence true and complete without knowing what came before. State what **is**, not what changed — git history records change; docs record the contract.
+Docs describe the current state only. Full rule set and enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
 
-- No historical/transitional language (`previously`, `now uses`, `instead of`, `migrated from`, `used to`, `no longer`, `as of`, `originally`, version-transition narration).
-- No references to the conversation that produced the doc (`as discussed`, `Option A`, `after Round 3`).
+## Private values stay out of the committed tree
 
-Full banned-pattern set + enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
-
-## GOTCHAS
-ALWAYS start each session with a /loop 15m populate or update the task list based on remaining todos.
+A value the code needs at run time that is itself private — a host, ssh user or port, owner scope, or id — lives in git-ignored local config with a committed placeholder, not in the source.
 
 ## Choosing Edit vs Write
 
@@ -45,7 +41,7 @@ Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compos
 Run every multi-step code task in two phases:
 
 1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
-2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
+2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Before it emits the verdict, it puts the draft through one strongest-tier validation subagent — selected per the advisor protocol's host detection and tier ladder — that tries to refute it, and it re-checks and corrects any part the validator overturns. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
 
 Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. The one exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments).
 
@@ -57,14 +53,12 @@ After any sub-agent returns a PR description, file list, or counts, verify each
 
 Track every task with the task tool, always — for all sessions and all tasks. Capture each task with `TaskCreate` as it arrives, mark it `in_progress` with `TaskUpdate` when you start, and `completed` when it is done. Run `/task-build` to gather any open tasks and add them to the list in one pass.
 
-## Working in the claude-code-config Repo
+## Working in the claude-dev-env Repo
 
 When changing how skills, rules, or hooks install or sync in this repo (for example adding a skill), read `docs/references/skill-install-system.md` — it maps the install pipeline in `packages/claude-dev-env/bin/install.mjs`.
 
 ## Additional Non-overlapping Rules
 
-- **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.
-- **confirm_implementation_forks:** When two or more viable paths would satisfy the goal and the choice changes the deliverable — its scope, completeness, deferred work, dependencies, or a hard-to-reverse contract — stop and ask which path via AskUserQuestion before implementing. A path that defers work or leaves a placeholder creating a follow-up task is itself a fork to surface, not a default to take silently. Phrase the question in plain language with only the detail needed to decide. See [`confirm-implementation-forks`](rules/confirm-implementation-forks.md).
 - **disambiguate_overloaded_terms:** When a word in the request has two different technical meanings — "conflict" (git-merge versus functional/behavioral), "sync" (fast-forward versus commit), and the like — confirm which one is meant via AskUserQuestion before analyzing or acting.
 
 ## Serena (Code Intelligence MCP)
@@ -87,31 +81,3 @@ Before any coding task, call the `initial_instructions` tool to load the Serena
 1. **Serena** — symbol-level navigation (declarations, references, implementations, rename)
 2. **es.exe** — file-system search by name/path/extension/size/date (Everything CLI)
 3. **Grep/Glob** — content and pattern matching
-
-## Everything Search (es.exe CLI)
-
-Search files by name, path, extension, size, or date with the Everything command-line tool `es.exe`. It reads the same live index the desktop app keeps, so results return instantly.
-
-### Invocation and scope tokens
-Run `es.exe` with a scoped query — a project path, an `ext:`/`dm:`/`size:` filter, or a name pattern. The `es_exe_path_rewriter` hook resolves a `{project-name}` placeholder or a bare registry key from `~/.claude/project-paths.json` into its quoted absolute path before the command runs (it allows and rewrites, never blocks).
-
-### Hard limits
-- Scope every search. A bare whole-drive scan or a network-share sweep is out of bounds.
-
-### Fallback order
-1. **es.exe** — file-system search by name/path/extension/size/date
-2. **Debug** — try to find out why es.exe isn't working, and then prompt user for next-steps if you can't self-heal.
-3. **Grep** — file-content search (Grep owns content)
-4. **Glob** — relative-path pattern matching within the current project
-
-### Search syntax quick reference
-- `ext:py` — find by extension (multiple: `ext:ts | ext:js`)
-- `path:src\components` — match against full path
-- `*.config.*` — wildcards
-- `size:>10mb` — size filter
-- `dm:today` / `dm:thisweek` — date modified filter
-- `-n 50` — limit results; `-sort dm` — sort by date modified
-- `foo bar` — AND, `foo | bar` — OR, `!foo` — NOT
-- `"exact phrase"` — literal match
-
-Full operator reference: `skills/everything-search/SKILL.md`.

package/_shared/CLAUDE.md

@@ -1,12 +1,13 @@
 # _shared
 
-Cross-cutting runtime assets shared by multiple PR-loop skills (`bugteam`, `pr-converge`, `findbugs`, `fixbugs`). Files here are installed into `~/.claude/_shared/` by `bin/install.mjs` alongside the skill directories that import them.
+Cross-cutting runtime assets shared by multiple skills. The PR-loop skills (`bugteam`, `pr-converge`, `findbugs`, `fixbugs`) are one such cluster; other clusters live here too. Files here are installed into `~/.claude/_shared/` by `bin/install.mjs` alongside the skill directories that import them.
 
 ## Contents
 
 | Entry | Description |
 |---|---|
 | `pr-loop/` | Docs, scripts, and constants for the PR-loop workflow suite |
+| `advisor/` | Warm-advisor spawn-and-consult protocol for `team-advisor` and `orchestrator` |
 
 ## Install path
 

package/_shared/advisor/CLAUDE.md

@@ -0,0 +1,21 @@
+# _shared/advisor
+
+Warm-advisor bind-and-consult protocol shared by `team-advisor`, `orchestrator`, `orchestrator-refresh`, and every executor subagent `orchestrator` routes work to. Changes here affect all of these simultaneously — treat this as a breaking-change surface.
+
+Host profile (Claude vs Grok) is detected first; Claude walks the multi-tier Agent spawn ladder, Grok self-binds as the advisor with a separate executor paste block.
+
+## Key documents
+
+| File | Purpose |
+|---|---|
+| `advisor-protocol.md` | Host profiles first, Claude-only model floor, warm-up spawn procedure and charter, consult format and cadence, lifecycle ownership (spawn on Claude / re-charter on Grok), host-matched Advisor blocks for executor spawns, and the Claude CLI fallback chain |
+
+## 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) |
+
+## Breaking-change rule
+
+A change to host detection, the model-floor rule, the charter template, either host's Advisor block, or lifecycle ownership in `advisor-protocol.md` requires updating every consuming skill (`team-advisor`, `orchestrator`, `orchestrator-refresh`) in the same commit.

package/_shared/advisor/advisor-protocol.md

@@ -0,0 +1,142 @@
+# 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.
+
+**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 Grok, skip straight to **Host profiles → Grok host**. On Claude, continue with **Model floor** and the rest of this document.
+
+## Host profiles
+
+Detect the host profile **before** any model-floor walk. Source of truth for names and detection: `HOST_PROFILE_CLAUDE`, `HOST_PROFILE_GROK`, `ALL_HOST_PROFILES`, and `detect_host_profile(...)` in `$HOME/.claude/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py` and `tier_model_ids.py`.
+
+Detection order:
+
+1. `ADVISOR_HOST_PROFILE=Grok` or `=Claude` (explicit override; any letter case).
+2. `GROK_BUILD=1` (or `true` / `yes` / `on`) — Grok Build / xAI harness.
+3. Default: Claude.
+
+### Claude 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.
+
+### Grok host
+
+Grok Build / xAI has exactly one model tier. Do **not** walk the Claude ladder and do **not** require a `claude` binary.
+
+1. Detect host profile first (this section).
+2. Set `own_tier = Grok`, `candidate_tiers = ["Grok"]`, one attempt only, `selected_tier = Grok`.
+3. **Self-as-advisor:** skip the Agent-tool spawn of `session-advisor`. The orchestrating Grok session *is* the advisor — the same process answers ENDORSE / CORRECTION / PLAN / STOP. Executors (when any) report blockers to the orchestrating session; that session answers with the four signals inline (or via its own same-session consult loop). There is no SendMessage-to-another-Claude-agent path on a pure Grok host.
+4. Record the single attempt as `{tier: "Grok", result: "self"}` — the `self` token marks a self-bind so logs stay honest (not a separate spawn).
+5. CLI Claude-chain fallback does **not** apply on a pure Grok host.
+6. Paste the **Grok host** Advisor block into every executor spawn prompt — never the Claude SendMessage block.
+
+Resolve the Grok alias with `resolve_cli_model_id("Grok")` → `grok` when a model field is required.
+
+## Model floor
+
+**Claude host only.** On a Grok host, skip this section entirely — follow **Host profiles → Grok 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.
+
+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 the warm-agent spawn top-down from Fable, stopping at the floor tier — never spawn below it. 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`). The warm agent is created at `selected_tier` (the first ladder tier that actually spawned), which may sit above the floor. If even the floor tier's spawn fails, move to the CLI fallback below rather than spawning below the floor.
+
+Emit a structured spawn-walk log so it can be checked mechanically rather than inferred from a transcript. Record: `own_tier` (the floor tier read at the top of this section), `candidate_tiers` (the ladder slice down to that floor), `attempts` (one `{tier, result}` entry appended as each spawn try happens, `result` one of `spawned` for a Claude Agent spawn, `self` for a Grok host self-bind, or a failure reason such as `unavailable`), and `selected_tier` (the tier of the first successful bind — first `spawned` or `self` entry — or `null` paired with a `fallback_reason` string when none bound and the CLI fallback took over). 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:
+
+```
+python "$HOME/.claude/_shared/advisor/scripts/model_tier_run_validator.py" <path-to-model-tier-run.json>
+```
+
+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)`.
+
+The validator checks ladder shape only (candidate slice, attempt order, success-token rules per tier). On a pure Grok host the protocol forbids CLI fallback after a failed self-bind; a log with `own_tier=Grok`, exhausted attempts, and `selected_tier=null` may still pass the structural validator — treat that as a host-policy violation outside the ladder checker.
+
+## Warm-up (once per session)
+
+On a Grok host, skip this section — follow **Host profiles → Grok host** (self-as-advisor; no Agent spawn walk).
+
+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 Fallback) — 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`.
+
+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. 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.
+
+The agent finishes its first turn standing by. `SendMessage` alone is what resumes it — no polling loop, no `ScheduleWakeup` keep-alive.
+
+## 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) or re-charter itself (Grok).
+
+## Advisor block — paste the host-matched block into every executor spawn prompt
+
+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.
+
+### Claude host (SendMessage to warm advisor)
+
+> 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.
+
+### Grok host (self-as-advisor; report to orchestrating session)
+
+> The orchestrating session is the shared advisor for this run — there is no separate `session-advisor` agent 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 answers with one of ENDORSE, CORRECTION, PLAN, or STOP — treat CORRECTION and PLAN as actions to take. On STOP, or if the orchestrating session is unreachable, stop work and surface that upward; do not spawn a `session-advisor` agent yourself.
+
+## 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.
+
+### Grok host
+
+The orchestrating session owns the self-as-advisor role for the whole run. There is no Agent spawn to end or respawn.
+
+**Re-charter on drift.** If the session's own answers show a stale picture, or the task pivots, re-state the self-as-advisor charter in-session (goal, four-signal contract, executor report path) and log another `{tier: "Grok", result: "self"}` bind only when a fresh structural log is needed. Executors keep reporting to the orchestrating session; they never spawn a replacement advisor.
+
+## Fallback: the CLI chain
+
+This section applies on a **Claude host** only. On a pure Grok host, skip it — there is no Claude binary chain and the session is already the advisor (see **Host profiles**).
+
+Fall back to the CLI 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.
+- `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` |
+| Grok (Grok host only; not part of the Claude walk) | `grok` |
+
+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`). Use `python "$HOME/.claude/scripts/claude_chain_runner.py" -- -p --model <model alias> --output-format json` in place of the Agent-tool spawn. The chain runner walks the fallback chain configured at `~/.claude/claude-chain.json` (typically `claude` then `claude-ev`), so a usage-limited primary account still gets served. 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 response 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 the fallback path from there.
+
+## Mechanism, not a measured saving
+
+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.

package/_shared/advisor/scripts/config/advisor_scripts_constants/__init__.py

@@ -0,0 +1 @@
+"""Named constants for the advisor scripts."""

package/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py

@@ -0,0 +1,86 @@
+"""Constants for the model-tier-run validator and CLI / Agent alias map.
+
+They name the parts of a spawn-walk log: the tier ladder (strongest
+first), the two host profiles, the spawn-log dict keys, and the tokens
+that mark a bind.
+
+::
+
+    attempt = {"tier": "Opus", "result": "spawned"}
+                       ^^^^^^           ^^^^^^^^^
+                       a ladder tier    SPAWN_SUCCESS_TOKEN
+    ok:   "self" marks a Grok host self-bind (SELF_BIND_SUCCESS_TOKEN)
+    flag: any other result token counts as no bind
+
+The alias map turns each tier into its short CLI / Agent name (``opus``,
+``grok``), never a dated full model ID.
+
+Host-profile detection (see ``detect_host_profile``):
+
+- ``ADVISOR_HOST_PROFILE=Grok`` or ``=Claude`` — explicit override
+- ``GROK_BUILD=1`` (or ``true`` / ``yes``) — Grok Build / xAI harness
+- default when neither is set: Claude
+"""
+
+from __future__ import annotations
+
+HOST_PROFILE_CLAUDE: str = "Claude"
+HOST_PROFILE_GROK: str = "Grok"
+ALL_HOST_PROFILES: tuple[str, ...] = (HOST_PROFILE_CLAUDE, HOST_PROFILE_GROK)
+
+ALL_MODEL_TIERS: tuple[str, ...] = ("Fable", "Opus", "Sonnet", "Haiku")
+GROK_MODEL_TIER: str = "Grok"
+ALL_KNOWN_TIER_NAMES: tuple[str, ...] = (*ALL_MODEL_TIERS, GROK_MODEL_TIER)
+
+ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS: int = 120
+
+ALL_CLI_MODEL_ID_BY_TIER: dict[str, str] = {
+    "Fable": "fable",
+    "Opus": "opus",
+    "Sonnet": "sonnet",
+    "Haiku": "haiku",
+    GROK_MODEL_TIER: "grok",
+}
+
+HOST_PROFILE_ENV_VAR: str = "ADVISOR_HOST_PROFILE"
+GROK_BUILD_ENV_VAR: str = "GROK_BUILD"
+ALL_GROK_BUILD_TRUTHY_VALUES: frozenset[str] = frozenset(
+    {"1", "true", "yes", "on"}
+)
+
+TIER_KEY: str = "tier"
+SPAWN_OUTCOME_KEY: str = "result"
+SPAWN_SUCCESS_TOKEN: str = "spawned"
+SELF_BIND_SUCCESS_TOKEN: str = "self"
+
+UNKNOWN_OWN_TIER_MESSAGE: str = "own_tier is not a known model tier"
+UNKNOWN_LADDER_NAME_ERROR: str = "ladder name is not a known model tier: {!r}"
+UNKNOWN_HOST_PROFILE_ERROR: str = "host profile is not a known profile: {!r}"
+CANDIDATE_TIERS_MISMATCH_MESSAGE: str = (
+    "candidate_tiers does not match the ladder slice down to own_tier"
+)
+ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE: str = (
+    "a spawn try names a tier outside the candidate slice"
+)
+ATTEMPT_ORDER_MISMATCH_MESSAGE: str = (
+    "spawn tries do not walk the candidate tiers in ladder order"
+)
+SELECTED_TIER_MISMATCH_MESSAGE: str = (
+    "selected_tier does not match the first successful bind (spawned or self)"
+)
+SELECTED_TIER_NOT_NULL_MESSAGE: str = (
+    "selected_tier must be null when no spawn try succeeded"
+)
+MISSING_FALLBACK_REASON_MESSAGE: str = (
+    "fallback_reason is required when no spawn try succeeded"
+)
+INCOMPLETE_FALLBACK_WALK_MESSAGE: str = (
+    "selected_tier is null but attempts did not exhaust every candidate tier"
+)
+CLI_USAGE_MESSAGE: str = (
+    "usage: model_tier_run_validator.py <spawn-walk-log.json>"
+)
+CLI_MISSING_PATH_EXIT_CODE: int = 2
+CLI_INVALID_JSON_EXIT_CODE: int = 2
+CLI_VALIDATION_FAILURE_EXIT_CODE: int = 1
+CLI_SUCCESS_EXIT_CODE: int = 0

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -0,0 +1,246 @@
+"""Mechanically validate a model-tier spawn-walk log.
+
+The advisor protocol's Model floor section emits a structured spawn-walk log.
+This validator reads that log back and checks its invariants. A run is judged
+from data, not inferred from a transcript.
+
+::
+
+    ladder_walk = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[
+            {"tier": "Fable", "result": "unavailable"},
+            {"tier": "Opus", "result": "spawned"},
+        ],
+        selected_tier="Opus",
+    )
+    validate_model_tier_run(ladder_walk)  # ok: returns None, raises nothing
+
+    self_bind = ModelTierRun(
+        own_tier="Grok",
+        candidate_tiers=["Grok"],
+        attempts=[{"tier": "Grok", "result": "self"}],
+        selected_tier="Grok",
+    )
+    validate_model_tier_run(self_bind)  # ok: host self-as-advisor bind
+
+A run whose selected_tier is not the first successful bind fails.
+On any broken invariant, validate_model_tier_run raises ModelTierRunError.
+
+CLI::
+
+    python model_tier_run_validator.py path/to/spawn-walk-log.json
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+_scripts_directory = str(Path(__file__).resolve().parent)
+_config_directory = str(Path(__file__).resolve().parent / "config")
+if _config_directory not in sys.path:
+    sys.path.insert(0, _config_directory)
+if _scripts_directory not in sys.path:
+    sys.path.insert(0, _scripts_directory)
+
+from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
+    ALL_MODEL_TIERS,
+    ATTEMPT_ORDER_MISMATCH_MESSAGE,
+    ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE,
+    CANDIDATE_TIERS_MISMATCH_MESSAGE,
+    CLI_INVALID_JSON_EXIT_CODE,
+    CLI_MISSING_PATH_EXIT_CODE,
+    CLI_SUCCESS_EXIT_CODE,
+    CLI_USAGE_MESSAGE,
+    CLI_VALIDATION_FAILURE_EXIT_CODE,
+    GROK_MODEL_TIER,
+    INCOMPLETE_FALLBACK_WALK_MESSAGE,
+    MISSING_FALLBACK_REASON_MESSAGE,
+    SELECTED_TIER_MISMATCH_MESSAGE,
+    SELECTED_TIER_NOT_NULL_MESSAGE,
+    SELF_BIND_SUCCESS_TOKEN,
+    SPAWN_OUTCOME_KEY,
+    SPAWN_SUCCESS_TOKEN,
+    TIER_KEY,
+    UNKNOWN_OWN_TIER_MESSAGE,
+)
+from tier_model_ids import canonical_tier_name  # noqa: E402
+
+
+@dataclass(frozen=True)
+class ModelTierRun:
+    own_tier: str
+    candidate_tiers: list[str]
+    attempts: list[dict[str, str]]
+    selected_tier: str | None
+    fallback_reason: str | None = None
+
+
+class ModelTierRunError(ValueError):
+    """Raised when a model-tier spawn-walk log violates an invariant."""
+
+
+def _canonical_tier_list(all_tier_names: list[str]) -> list[str] | None:
+    all_canonical_tiers: list[str] = []
+    for each_tier_name in all_tier_names:
+        maybe_canonical_tier = canonical_tier_name(each_tier_name)
+        if maybe_canonical_tier is None:
+            return None
+        all_canonical_tiers.append(maybe_canonical_tier)
+    return all_canonical_tiers
+
+
+def _expected_candidate_tiers(own_tier: str) -> list[str]:
+    maybe_canonical_own_tier = canonical_tier_name(own_tier)
+    if maybe_canonical_own_tier is None:
+        raise ModelTierRunError(f"{UNKNOWN_OWN_TIER_MESSAGE}: {own_tier!r}")
+    if maybe_canonical_own_tier == GROK_MODEL_TIER:
+        return [GROK_MODEL_TIER]
+    floor_index = ALL_MODEL_TIERS.index(maybe_canonical_own_tier)
+    return list(ALL_MODEL_TIERS[: floor_index + 1])
+
+
+def _is_successful_attempt_outcome(
+    canonical_tier: str,
+    outcome_token: str,
+) -> bool:
+    if canonical_tier == GROK_MODEL_TIER:
+        return outcome_token == SELF_BIND_SUCCESS_TOKEN
+    return outcome_token == SPAWN_SUCCESS_TOKEN
+
+
+def validate_model_tier_run(run: ModelTierRun) -> None:
+    """Check that a spawn-walk log satisfies every ladder invariant.
+
+    ::
+
+        validate_model_tier_run(ladder_walk)  # ok: multi-tier ladder walk
+        validate_model_tier_run(self_bind)    # ok: single-tier self-bind
+        validate_model_tier_run(broken_log)   # flag: ModelTierRunError
+
+    Candidate tiers must match the floor slice (or ``["Grok"]`` alone). Tries
+    walk that slice in order; early stop only after ``spawned`` or ``self``.
+    A null selected_tier requires a full walk plus fallback_reason.
+
+    Args:
+        run: The structured spawn-walk log to check.
+
+    Returns:
+        None when every invariant holds.
+
+    Raises:
+        ModelTierRunError: When any invariant is violated.
+    """
+    all_expected_candidates = _expected_candidate_tiers(run.own_tier)
+    maybe_canonical_candidates = _canonical_tier_list(run.candidate_tiers)
+    if maybe_canonical_candidates != all_expected_candidates:
+        raise ModelTierRunError(CANDIDATE_TIERS_MISMATCH_MESSAGE)
+    maybe_attempted_tiers = _canonical_tier_list(
+        [each_attempt[TIER_KEY] for each_attempt in run.attempts]
+    )
+    if maybe_attempted_tiers is None:
+        raise ModelTierRunError(ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE)
+    all_attempted_tiers = maybe_attempted_tiers
+    if any(
+        each_tier not in all_expected_candidates for each_tier in all_attempted_tiers
+    ):
+        raise ModelTierRunError(ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE)
+    if all_attempted_tiers != all_expected_candidates[: len(all_attempted_tiers)]:
+        raise ModelTierRunError(ATTEMPT_ORDER_MISMATCH_MESSAGE)
+    _validate_selected_tier(
+        run=run,
+        all_attempted_tiers=all_attempted_tiers,
+        all_expected_candidates=all_expected_candidates,
+    )
+
+
+def _validate_selected_tier(
+    run: ModelTierRun,
+    all_attempted_tiers: list[str],
+    all_expected_candidates: list[str],
+) -> None:
+    all_bound_tiers = [
+        each_tier
+        for each_tier, each_attempt in zip(
+            all_attempted_tiers, run.attempts, strict=True
+        )
+        if _is_successful_attempt_outcome(
+            canonical_tier=each_tier,
+            outcome_token=each_attempt[SPAWN_OUTCOME_KEY],
+        )
+    ]
+    if all_bound_tiers:
+        maybe_canonical_selected = (
+            canonical_tier_name(run.selected_tier)
+            if run.selected_tier is not None
+            else None
+        )
+        if maybe_canonical_selected != all_bound_tiers[0]:
+            raise ModelTierRunError(SELECTED_TIER_MISMATCH_MESSAGE)
+        return
+    if run.selected_tier is not None:
+        raise ModelTierRunError(SELECTED_TIER_NOT_NULL_MESSAGE)
+    if not all_attempted_tiers or all_attempted_tiers != all_expected_candidates:
+        raise ModelTierRunError(INCOMPLETE_FALLBACK_WALK_MESSAGE)
+    if not run.fallback_reason:
+        raise ModelTierRunError(MISSING_FALLBACK_REASON_MESSAGE)
+
+
+def load_model_tier_run_from_json_path(from_path: Path) -> ModelTierRun:
+    """Load a ModelTierRun from a JSON spawn-walk log file.
+
+    Args:
+        from_path: Path to a JSON object with ModelTierRun fields.
+
+    Returns:
+        The parsed ModelTierRun.
+
+    Raises:
+        OSError: When the file cannot be read.
+        json.JSONDecodeError: When the file is not valid JSON.
+        KeyError: When a required field is missing.
+        TypeError: When a field has the wrong shape.
+    """
+    parsed_payload = json.loads(from_path.read_text(encoding="utf-8"))
+    return ModelTierRun(
+        own_tier=parsed_payload["own_tier"],
+        candidate_tiers=list(parsed_payload["candidate_tiers"]),
+        attempts=list(parsed_payload["attempts"]),
+        selected_tier=parsed_payload.get("selected_tier"),
+        fallback_reason=parsed_payload.get("fallback_reason"),
+    )
+
+
+def main(all_cli_arguments: list[str]) -> int:
+    """Validate a spawn-walk log JSON file from the command line.
+
+    Args:
+        all_cli_arguments: Argument list without the program name.
+
+    Returns:
+        ``0`` when the log is valid, ``1`` when an invariant fails, ``2`` when
+        the path or JSON was unusable.
+    """
+    if len(all_cli_arguments) != 1:
+        print(CLI_USAGE_MESSAGE, file=sys.stderr)
+        return CLI_MISSING_PATH_EXIT_CODE
+    log_path = Path(all_cli_arguments[0])
+    try:
+        model_tier_run = load_model_tier_run_from_json_path(from_path=log_path)
+    except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as load_error:
+        print(str(load_error), file=sys.stderr)
+        return CLI_INVALID_JSON_EXIT_CODE
+    try:
+        validate_model_tier_run(model_tier_run)
+    except ModelTierRunError as validation_error:
+        print(str(validation_error), file=sys.stderr)
+        return CLI_VALIDATION_FAILURE_EXIT_CODE
+    return CLI_SUCCESS_EXIT_CODE
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/_shared/advisor/scripts/pyproject.toml

@@ -0,0 +1,3 @@
+[tool.mypy]
+mypy_path = "config"
+ignore_missing_imports = true