claude-dev-env 1.94.0 → 1.95.0

package/_shared/advisor/CLAUDE.md

@@ -2,13 +2,13 @@
 
 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.
+Host profile (Claude vs Grok) is detected first; Claude walks the multi-tier Agent spawn ladder (CLI chain as fallback), Grok binds a max-tier Claude advisor through the CLI Claude-chain (fail closed when the chain cannot serve) 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 |
+| `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 Grok), host-matched Advisor blocks for executor spawns, and the shared CLI Claude-chain |
 
 ## Subdirectory
 

package/_shared/advisor/advisor-protocol.md

@@ -20,28 +20,34 @@ Use the **Model floor** ladder below (Fable → Opus → Sonnet → Haiku). Warm
 
 ### Grok host
 
-Grok Build / xAI has exactly one model tier. Do **not** walk the Claude ladder and do **not** require a `claude` binary.
+Grok Build / xAI cannot spawn a Claude `session-advisor` through the Agent tool. Bind a **max-tier Claude advisor** through the shared CLI Claude-chain (account usage failover). Do **not** treat this Grok session as the advisor.
 
 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.
+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 Grok host.
+3. **CLI bind (primary path):** for each candidate top-down, pipe a charter file into:
 
-Resolve the Grok alias with `resolve_cli_model_id("Grok")` → `grok` when a model field is required.
+   ```
+   python "$HOME/.claude/scripts/claude_chain_runner.py" -- -p --model <alias> --effort <effort> --output-format json
+   ```
 
-## Model floor
+   Use `--model fable --effort high` on Fable; use `--model opus --effort max` on Opus. The chain runner walks `~/.claude/claude-chain.json` (binaries such as `claude`, `claude-ev`, `claude-editor`, `claude-mel`) and fails over only on a usage-limit signature.
+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; 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 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 Grok session. Do **not** self-endorse.
+6. Paste the **Grok 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.
+
+Resolve a Grok session's own model field with `resolve_cli_model_id("Grok")` → `grok` when a host model alias is required. The **advisor** bind uses Fable/Opus aliases only.
 
-**Claude host only.** On a Grok host, skip this section entirely — follow **Host profiles → Grok host**.
+## Model floor
 
-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:
+**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.
 
-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.
+**Grok host:** the CLI advisor floor is fixed at **Opus** (walk Fable → Opus only). The Grok session's own tier is not the advisor floor — see **Host profiles → Grok host**.
 
-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:
+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 Grok host each walk attempt uses the CLI chain with that alias and the effort flags in **Host profiles → Grok 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 Grok host the CLI chain **is** the primary path, so floor failure is fail-closed (report unreachable).
+
+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:
 
 ```
 python "$HOME/.claude/_shared/advisor/scripts/model_tier_run_validator.py" <path-to-model-tier-run.json>
@@ -49,15 +55,15 @@ python "$HOME/.claude/_shared/advisor/scripts/model_tier_run_validator.py" <path
 
 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.
+The validator checks ladder shape only (candidate slice, attempt order, success-token rules per tier). Host policy on top: a Grok host with `selected_tier=null` after an exhausted Fable→Opus walk must fail closed (report unreachable; never self-endorse).
 
 ## 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 **Grok host**, follow **Host profiles → Grok 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:
+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.
+- `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`.
 
@@ -86,7 +92,7 @@ Each consult carries, in order: who you are and your assignment (only needed on
 
 **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).
+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 Grok CLI re-bind). A Grok host that cannot re-bind fails closed and reports to the user — it does not answer the four signals as itself.
 
 ## Advisor block — paste the host-matched block into every executor spawn prompt
 
@@ -96,9 +102,9 @@ Each paragraph is self-contained — the executor receives only this text, not t
 
 > 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)
+### Grok host (Claude CLI 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.
+> 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 Grok orchestrator's own judgment as an advisor signal.
 
 ## Lifecycle ownership
 
@@ -110,15 +116,17 @@ The session that spawns the shared advisor owns its whole lifecycle — spawn, d
 
 ### Grok host
 
-The orchestrating session owns the self-as-advisor role for the whole run. There is no Agent spawn to end or respawn.
+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.
 
-**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.
+## CLI chain
 
-## Fallback: the CLI chain
+The shared runner is `python "$HOME/.claude/scripts/claude_chain_runner.py" -- <claude args...>`. It walks `~/.claude/claude-chain.json` and fails over to the next binary only on a usage-limit signature, so a usage-limited primary account still gets served.
 
-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**).
+**Grok host:** this runner is the **primary** advisor bind and consult path (see **Host profiles → Grok host**). Map each walk attempt to `--model <alias>` and the effort flags there. When the walk exhausts, fail closed.
 
-Fall back to the CLI when any of these holds, rather than on judgment call:
+**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.
 - `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.
@@ -131,11 +139,11 @@ Map `selected_tier` when one exists (the warm agent already bound above the floo
 | Opus | `opus` |
 | Sonnet | `sonnet` |
 | Haiku | `haiku` |
-| Grok (Grok host only; not part of the Claude walk) | `grok` |
+| Grok (Grok session model field only; not an advisor walk tier) | `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.
+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 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.
+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
 

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

@@ -9,7 +9,7 @@ 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)
+    ok:   "cli" marks a CLI Claude-chain bind (CLI_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``,
@@ -31,6 +31,7 @@ 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)
+GROK_CLI_ADVISOR_FLOOR_TIER: str = "Opus"
 
 ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS: int = 120
 
@@ -51,7 +52,7 @@ ALL_GROK_BUILD_TRUTHY_VALUES: frozenset[str] = frozenset(
 TIER_KEY: str = "tier"
 SPAWN_OUTCOME_KEY: str = "result"
 SPAWN_SUCCESS_TOKEN: str = "spawned"
-SELF_BIND_SUCCESS_TOKEN: str = "self"
+CLI_BIND_SUCCESS_TOKEN: str = "cli"
 
 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}"

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -17,13 +17,13 @@ from data, not inferred from a transcript.
     )
     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",
+    cli_bind = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[{"tier": "Fable", "result": "cli"}],
+        selected_tier="Fable",
     )
-    validate_model_tier_run(self_bind)  # ok: host self-as-advisor bind
+    validate_model_tier_run(cli_bind)  # ok: Grok-host CLI Claude-chain bind
 
 A run whose selected_tier is not the first successful bind fails.
 On any broken invariant, validate_model_tier_run raises ModelTierRunError.
@@ -52,17 +52,18 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (  # no
     ATTEMPT_ORDER_MISMATCH_MESSAGE,
     ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE,
     CANDIDATE_TIERS_MISMATCH_MESSAGE,
+    CLI_BIND_SUCCESS_TOKEN,
     CLI_INVALID_JSON_EXIT_CODE,
     CLI_MISSING_PATH_EXIT_CODE,
     CLI_SUCCESS_EXIT_CODE,
     CLI_USAGE_MESSAGE,
     CLI_VALIDATION_FAILURE_EXIT_CODE,
+    GROK_CLI_ADVISOR_FLOOR_TIER,
     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,
@@ -99,7 +100,8 @@ def _expected_candidate_tiers(own_tier: str) -> list[str]:
     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(GROK_CLI_ADVISOR_FLOOR_TIER)
+        return list(ALL_MODEL_TIERS[: floor_index + 1])
     floor_index = ALL_MODEL_TIERS.index(maybe_canonical_own_tier)
     return list(ALL_MODEL_TIERS[: floor_index + 1])
 
@@ -109,8 +111,12 @@ def _is_successful_attempt_outcome(
     outcome_token: str,
 ) -> bool:
     if canonical_tier == GROK_MODEL_TIER:
-        return outcome_token == SELF_BIND_SUCCESS_TOKEN
-    return outcome_token == SPAWN_SUCCESS_TOKEN
+        return False
+    if outcome_token == SPAWN_SUCCESS_TOKEN:
+        return True
+    if outcome_token == CLI_BIND_SUCCESS_TOKEN:
+        return True
+    return False
 
 
 def validate_model_tier_run(run: ModelTierRun) -> None:
@@ -118,13 +124,15 @@ def validate_model_tier_run(run: ModelTierRun) -> None:
 
     ::
 
-        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(ladder_walk)  # ok: multi-tier Agent walk
+        validate_model_tier_run(cli_bind)     # ok: CLI Claude-chain 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.
+    Candidate tiers must match the floor slice. ``own_tier=Grok`` maps to the
+    Grok-host CLI advisor floor (Fable → Opus). Tries walk that slice in order;
+    early stop only after ``spawned`` or ``cli``. A null selected_tier requires
+    a full walk plus fallback_reason (fail-closed on Grok when the chain
+    cannot serve).
 
     Args:
         run: The structured spawn-walk log to check.

package/_shared/advisor/scripts/tests/test_model_tier_run_validator.py

@@ -238,53 +238,117 @@ def test_cli_missing_path_returns_usage_exit_code() -> None:
     assert main([]) == 2
 
 
-def test_grok_host_single_tier_self_bind_passes() -> None:
+def test_cli_bind_at_fable_passes() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[{"tier": "Fable", "result": "cli"}],
+        selected_tier="Fable",
+    )
+    assert validate_model_tier_run(run) is None
+
+
+def test_cli_bind_fallthrough_to_opus_passes() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[
+            {"tier": "Fable", "result": "unavailable"},
+            {"tier": "Opus", "result": "cli"},
+        ],
+        selected_tier="Opus",
+    )
+    assert validate_model_tier_run(run) is None
+
+
+def test_grok_own_tier_maps_to_fable_opus_cli_bind_passes() -> None:
     run = ModelTierRun(
         own_tier="Grok",
-        candidate_tiers=["Grok"],
-        attempts=[{"tier": "Grok", "result": "self"}],
-        selected_tier="Grok",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[{"tier": "Fable", "result": "cli"}],
+        selected_tier="Fable",
     )
     assert validate_model_tier_run(run) is None
 
 
-def test_grok_host_lowercase_self_bind_passes() -> None:
+def test_grok_own_tier_lowercase_cli_bind_passes() -> None:
     run = ModelTierRun(
         own_tier="grok",
-        candidate_tiers=["grok"],
-        attempts=[{"tier": "grok", "result": "self"}],
-        selected_tier="grok",
+        candidate_tiers=["fable", "opus"],
+        attempts=[{"tier": "fable", "result": "cli"}],
+        selected_tier="fable",
     )
     assert validate_model_tier_run(run) is None
 
 
-def test_grok_host_multi_tier_candidate_list_raises() -> None:
+def test_self_token_is_not_bind_success_raises() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[{"tier": "Fable", "result": "self"}],
+        selected_tier="Fable",
+    )
+    with pytest.raises(ModelTierRunError):
+        validate_model_tier_run(run)
+
+
+def test_grok_self_token_is_not_bind_success_raises() -> None:
     run = ModelTierRun(
         own_tier="Grok",
-        candidate_tiers=["Fable", "Opus", "Grok"],
-        attempts=[{"tier": "Grok", "result": "self"}],
-        selected_tier="Grok",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[{"tier": "Fable", "result": "self"}],
+        selected_tier="Fable",
     )
     with pytest.raises(ModelTierRunError):
         validate_model_tier_run(run)
 
 
-def test_grok_host_spawned_token_is_not_self_bind_raises() -> None:
+def test_grok_host_legacy_single_tier_self_bind_raises() -> None:
     run = ModelTierRun(
         own_tier="Grok",
         candidate_tiers=["Grok"],
-        attempts=[{"tier": "Grok", "result": "spawned"}],
+        attempts=[{"tier": "Grok", "result": "self"}],
         selected_tier="Grok",
     )
     with pytest.raises(ModelTierRunError):
         validate_model_tier_run(run)
 
 
-def test_grok_host_selected_tier_mismatch_raises() -> None:
+def test_grok_cli_exhausted_fail_closed_passes() -> None:
     run = ModelTierRun(
         own_tier="Grok",
-        candidate_tiers=["Grok"],
-        attempts=[{"tier": "Grok", "result": "self"}],
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[
+            {"tier": "Fable", "result": "unavailable"},
+            {"tier": "Opus", "result": "unavailable"},
+        ],
+        selected_tier=None,
+        fallback_reason=(
+            "Grok host CLI Claude-chain exhausted; fail closed"
+        ),
+    )
+    assert validate_model_tier_run(run) is None
+
+
+def test_grok_cli_exhausted_without_fallback_reason_raises() -> None:
+    run = ModelTierRun(
+        own_tier="Grok",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[
+            {"tier": "Fable", "result": "unavailable"},
+            {"tier": "Opus", "result": "unavailable"},
+        ],
+        selected_tier=None,
+    )
+    with pytest.raises(ModelTierRunError):
+        validate_model_tier_run(run)
+
+
+def test_grok_cli_selected_tier_mismatch_raises() -> None:
+    run = ModelTierRun(
+        own_tier="Grok",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[{"tier": "Fable", "result": "cli"}],
         selected_tier="Opus",
     )
     with pytest.raises(ModelTierRunError):

package/bin/CLAUDE.md

@@ -6,7 +6,8 @@ The installer and its companion modules. Running `npx claude-dev-env` (or `node
 
 | File | Purpose |
 |---|---|
-| `install.mjs` | Main installer: discovers install groups, copies content directories (`rules`, `docs`, `commands`, `agents`, `system-prompts`, `scripts`, `_shared`, `audit-rubrics`), merges hooks into `settings.json`, installs skills, runs `git_hooks_installer.mjs` and `install_mypy_ini.mjs` |
+| `install.mjs` | Main installer: discovers install groups, copies content directories (`rules`, `docs`, `commands`, `agents`, `system-prompts`, `scripts`, `_shared`, `audit-rubrics`), merges hooks into `settings.json`, installs skills, prunes retired skills on a full install, runs `git_hooks_installer.mjs` and `install_mypy_ini.mjs` |
+| `ever-shipped-skills.mjs` | Static `EVER_SHIPPED_SKILL_NAMES` set of every top-level skill directory name the package has shipped; the installer subtracts the current skill set from it to prune retired skills left under `~/.claude/skills` |
 | `expand_home_directory_tokens.mjs` | Expands residual `$HOME` / `${HOME}` / `~/` tokens in settings.json hook and statusLine commands to absolute home paths at install time (literal-safe for homes that contain `$`) |
 | `git_hooks_installer.mjs` | Installs or updates the `pre-commit`, `pre-push`, and `post-commit` Git hooks in the user's git config; writes hook scripts that delegate to the installed Python hooks |
 | `install_mypy_ini.mjs` | Writes `~/.mypy.ini` with settings that make mypy find the hooks package and enforce strict type checking |
@@ -14,6 +15,14 @@ The installer and its companion modules. Running `npx claude-dev-env` (or `node
 | `git_hooks_installer.test.mjs` | Tests for `git_hooks_installer.mjs` |
 | `install_mypy_ini.test.mjs` | Tests for `install_mypy_ini.mjs` |
 
+## Retired-skill prune
+
+The full-install prune renames a retired skill directory into a timestamped backup rather than deleting it. Each pruned directory is renamed to `~/.claude/.claude-dev-env-pruned/<timestamp>/<skill-name>/`, a backup root outside `~/.claude/skills` so a backed-up directory is never re-discovered as a skill. Backups accumulate — nothing cleans them — so a user can recover a directory. A rename that fails leaves the directory in place with a logged warning and never falls back to deletion, so a prune failure costs at most a cosmetic leftover.
+
+Matching is by directory name alone, so a user-authored directory whose name collides with a retired skill is backed up as if it were that skill. A directory is pruned when the prior install's manifest recorded it or the ever-shipped set names it, and the current install did not just write it. A name absent from all three of those sets, together with `~/.claude/skills/_shared`, is left in place.
+
+The prune is skipped for the whole run — with a logged notice naming the unresolved group — when any declared dependency group fails to resolve. An unresolved dependency contributes no skills to the installed set, so a live skill that a dependency package supplies would look retired; holding the prune until every dependency resolves keeps such a skill from being backed up.
+
 ## Key exports from install.mjs
 
 | Export | Description |

package/bin/ever-shipped-skills.mjs

@@ -0,0 +1,70 @@
+/**
+ * The top-level skill directory names this package has ever shipped.
+ *
+ * The installer subtracts the skills the current package installs from this set
+ * to learn which shipped skills have retired, so a full reinstall can remove a
+ * retired skill left behind under ~/.claude/skills. Because the current set is
+ * subtracted at runtime, restoring a retired skill to the package protects it
+ * automatically — it re-enters the installed set and drops out of the retired
+ * set on the next install.
+ *
+ * The list is a committed literal rather than a git query, because a user
+ * installs from the npm tarball, which carries no source-repo history. Refresh
+ * it by running, from the repository root:
+ *
+ *   git log --all --pretty=format: --name-only -- 'packages/claude-dev-env/skills/*\/SKILL.md' | sort -u
+ *
+ * and pasting each distinct top-level skill directory name below.
+ */
+export const EVER_SHIPPED_SKILL_NAMES = new Set([
+    'anthropic-plan',
+    'auditing-claude-config',
+    'autoconverge',
+    'bdd-protocol',
+    'bg-agent',
+    'bugteam',
+    'caveman',
+    'code',
+    'copilot-finding-triage',
+    'copilot-review',
+    'deep-research',
+    'everything-search',
+    'findbugs',
+    'fixbugs',
+    'fresh-branch',
+    'gh-paginate',
+    'gotcha',
+    'grokify',
+    'implement',
+    'log-audit',
+    'logifix',
+    'monitor-open-prs',
+    'orchestrator',
+    'orchestrator-refresh',
+    'post-audit-findings',
+    'pr-consistency-audit',
+    'pr-converge',
+    'pr-fix-protocol',
+    'pr-loop-cloud-transport',
+    'pr-loop-lifecycle',
+    'pr-review-responder',
+    'pr-scope-resolve',
+    'pre-compact',
+    'privacy-hygiene',
+    'qbug',
+    'rebase',
+    'recall',
+    'refine',
+    'remember',
+    'research-mode',
+    'reviewer-gates',
+    'session-log',
+    'session-tidy',
+    'skill-builder',
+    'structure-prompt',
+    'task-build',
+    'team-advisor',
+    'update',
+    'usage-pause',
+    'verified-build',
+]);