claude-dev-env 1.93.1 → 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/_shared/pr-loop/CLAUDE.md

@@ -8,6 +8,7 @@ Runtime documents and scripts shared by every PR-loop skill. Changes here affect
 |---|---|
 | `audit-contract.md` | Canonical finding schema (Shape A / Shape B) and loop contract; defines the JSON shapes every audit skill must emit |
 | `audit-reply-template.md` | Canonical reply skeleton Claude posts to each unresolved review thread; single source of truth for reply structure |
+| `post-audit-thread-contract.md` | Single source of truth for the `post_audit_thread.py` invocation string, exit-code table, and per-caller policy (bugteam exit 2 = hard blocker; autoconverge clean-audit failed post = recorded bypass) |
 | `fix-protocol.md` | Ordered sequence a fix lens follows: read, capture SHA, TDD, apply, validate, self-audit, commit, push, reply + resolve |
 | `gh-payloads.md` | How to build GitHub review and reply payloads via MCP tools; describes the one-review-per-loop pattern |
 | `state-schema.md` | Fields each PR-loop workflow tracks across iterations; documents common fields and per-skill extensions |

package/_shared/pr-loop/audit-contract.md

@@ -120,7 +120,7 @@ Sequence:
 2. Apply edits.
 3. Run `py_compile` (or language-equivalent) on each modified file.
 4. Compute `fix_diff` against pre-fix contents for the modified set.
-5. Run `bugteam_code_rules_gate.py` with explicit paths for every modified file.
+5. Run `_shared/pr-loop/scripts/code_rules_gate.py` with explicit paths for every modified file.
 6. Spawn a scoped audit of `fix_diff` with full A–P rigor, Shape A/B contract, adversarial pass, AND Haiku secondary in parallel (paranoid mode on post-fix).
 7. Read the previous loop's outcome XML (`<worktree_path>/.bugteam-pr<N>-loop<L-1>.outcomes.xml`) and obtain its total finding count. If this is the first loop (L <= 1) or the file does not exist, skip this comparison. Compute the post-fix total: previous total minus bugs fixed in this round plus new violations found in the post-fix audit (step 6). If the post-fix total exceeds the previous total, flag all new findings as same-loop fix-targets and revise. An increase in total findings across loop transitions is a regression.
 8. Any new findings become same-loop fix-targets. Internal iteration count increments by one.

package/_shared/pr-loop/gh-payloads.md

@@ -55,9 +55,9 @@ user-facing output (chat reply to the user) rather than in the PR review body.
 
 ## Review POST failure
 
-There is no fallback path. `post_audit_thread.py` exits `2` on retry
-exhaustion (four non-2xx responses across the built-in `1s / 4s / 16s` backoff)
-and the orchestrator halts with `error: post_audit_thread retry exhausted`.
+There is no fallback payload to build. On retry exhaustion
+`post_audit_thread.py` exits `2` and the orchestrator halts — see
+[`./post-audit-thread-contract.md`](./post-audit-thread-contract.md) § Exit codes.
 A hard blocker on the audit-posting path is a halt condition, not a degraded
 flat-issue-comment fall-through.
 

package/_shared/pr-loop/post-audit-thread-contract.md

@@ -0,0 +1,51 @@
+# post_audit_thread.py invocation contract
+
+Single source of truth for how every PR-loop caller runs
+[`scripts/post_audit_thread.py`](scripts/post_audit_thread.py) to post one
+audit review per pass. The script posts an `APPROVE` review on `CLEAN` (an
+empty findings list, zero inline comments) and a `REQUEST_CHANGES` review on
+`DIRTY` (one inline anchored comment per finding). It reads its body skeleton
+from [`audit-reply-template.md`](audit-reply-template.md) at runtime.
+
+## Invocation
+
+```
+python "<pr-loop-scripts>/post_audit_thread.py" \
+  --skill <caller> \
+  --owner <owner> \
+  --repo <repo> \
+  --pr-number <N> \
+  --commit <head_sha> \
+  --state <CLEAN|DIRTY> \
+  --findings-json <path>
+```
+
+Capture `<head_sha>` with `git rev-parse HEAD` in the caller's cwd right before
+the call, so the review attaches to the commit the audit scoped. `--findings-json`
+points to a JSON file whose root is a list; on `CLEAN` the list is empty (`[]`).
+
+## Exit codes
+
+The script retries on its own with 1s / 4s / 16s backoff across four tries (one
+plus three retries). It then exits:
+
+| Exit | Meaning |
+|---|---|
+| `0` | Review posted. The new review's `html_url` is on stdout. |
+| `1` | User input error: bad arguments, malformed findings JSON, or a missing template. |
+| `2` | Retry exhaustion: every try failed. |
+
+## Per-caller policy
+
+The same exit codes carry different weight per caller:
+
+- **bugteam** — an exit `2` is a hard blocker. The lead exits with
+  `error: post_audit_thread retry exhausted`, and does not retry or fall back to
+  a flat issue comment.
+- **autoconverge clean-audit** — any post that does not land (a denied post, an
+  error, or an agent that never ran) is a recorded bypass, not a blocker. Every
+  review lens already cleared the HEAD, so the CLEAN post is a record-keeping
+  artifact. The run records a bypass note, sets the convergence check's
+  `--bugteam-post-blocked` flag, and proceeds to the terminal Bugbot gate. Full
+  policy: [`../../skills/autoconverge/reference/stop-conditions.md`](../../skills/autoconverge/reference/stop-conditions.md)
+  § "Clean-audit post bypassed".

package/_shared/pr-loop/scripts/README.md

@@ -9,11 +9,11 @@ Runnable helpers used by **bugteam**, **qbug**, **pr-converge**, and related ski
 | `preflight.py` | Local checks before a PR-loop run (pytest discovery, optional pre-commit, hooksPath sanity). |
 | `reviewer_availability.py` | Unified availability check for Copilot and Bugbot; reuses `copilot_quota.py` and `reviews_disabled.py` and exits 0 when the named `--reviewer` may be spawned. |
 | `code_rules_gate.py` | CODE_RULES gate over PR-scoped diffs (`--base`, staged-only, path filters). |
-| `fix_hookspath.py` | Repair `core.hooksPath` when it does not point at the packaged git-hooks tree. |
+| `fix_hookspath.py` | Repair `core.hooksPath` when it does not point at the packaged git-hooks tree. Single home for unexpected non-empty git stderr (hard-fail `RuntimeError`); skill wrappers may call it later. |
 | `grant_project_claude_permissions.py` / `revoke_project_claude_permissions.py` | Claude Code permission JSON helpers used during publish-style flows. |
 | `_claude_permissions_common.py` | Shared implementation for the permission scripts. |
 
-Configuration lives under `config/` next to these scripts (for example `preflight_constants.py`, `code_rules_gate_constants.py`).
+Configuration lives under `pr_loop_shared_constants/` next to these scripts (for example `preflight_constants.py`, `code_rules_gate_constants.py`, `fix_hookspath_constants.py`).
 
 ## Gate semantics
 

package/_shared/pr-loop/scripts/fix_hookspath.py

@@ -53,6 +53,9 @@ def list_local_core_hooks_path_values(
     Returns:
         Non-empty stripped values from ``git config --local --get-all``, or
         an empty list when no values are configured.
+
+    Raises:
+        RuntimeError: When git exits non-zero with a non-empty stderr diagnostic.
     """
     git_command = [
         "git",
@@ -75,11 +78,9 @@ def list_local_core_hooks_path_values(
     if completed_process.returncode != 0:
         diagnostic_stderr = completed_process.stderr.strip()
         if diagnostic_stderr:
-            print(
-                "fix_hookspath: git read of local core.hooksPath on "
-                f"{repository_root} exited {completed_process.returncode}: "
-                f"{diagnostic_stderr}",
-                file=sys.stderr,
+            raise RuntimeError(
+                f"git read of local core.hooksPath on {repository_root} "
+                f"exited {completed_process.returncode}: {diagnostic_stderr}"
             )
         return []
     return [
@@ -99,8 +100,11 @@ def read_global_core_hooks_path(
             forwarded to ``subprocess.run``.
 
     Returns:
-        The stripped global value, or an empty string when unset or when git
-        returns non-zero.
+        The stripped global value, or an empty string when the key is unset
+        (git exits non-zero with empty stderr).
+
+    Raises:
+        RuntimeError: When git exits non-zero with a non-empty stderr diagnostic.
     """
     git_command = list(ALL_GIT_GLOBAL_GET_CORE_HOOKS_PATH_COMMAND)
     completed_process = subprocess.run(
@@ -115,10 +119,9 @@ def read_global_core_hooks_path(
     if completed_process.returncode != 0:
         diagnostic_stderr = completed_process.stderr.strip()
         if diagnostic_stderr:
-            print(
-                "fix_hookspath: git read of global core.hooksPath exited "
-                f"{completed_process.returncode}: {diagnostic_stderr}",
-                file=sys.stderr,
+            raise RuntimeError(
+                f"git read of global core.hooksPath exited "
+                f"{completed_process.returncode}: {diagnostic_stderr}"
             )
         return ""
     return completed_process.stdout.strip()
@@ -280,7 +283,8 @@ def main(
             forwarded to every git invocation and to the preflight rerun.
 
     Returns:
-        Zero on success. Non-zero on the first failing git command or on a
+        Zero on success. Non-zero on the first failing git command, on a
+        hard-fail git stderr diagnostic (caught ``RuntimeError``), or on a
         non-zero preflight rerun exit code.
     """
     arguments = parse_arguments(all_arguments)
@@ -302,6 +306,37 @@ def main(
             file=sys.stderr,
         )
         return 1
+    try:
+        return _repair_hooks_path_then_rerun_preflight(
+            repository_root=repository_root,
+            canonical_hooks_directory=canonical_hooks_directory,
+            all_environment_overrides=all_environment_overrides,
+        )
+    except RuntimeError as runtime_error:
+        print(f"fix_hookspath: {runtime_error}", file=sys.stderr)
+        return 1
+
+
+def _repair_hooks_path_then_rerun_preflight(
+    repository_root: Path,
+    canonical_hooks_directory: Path,
+    all_environment_overrides: dict[str, str] | None,
+) -> int:
+    """Apply local/global hooksPath repairs, then re-run preflight.
+
+    Args:
+        repository_root: Repository root used for local git config and preflight.
+        canonical_hooks_directory: Absolute path to the packaged git-hooks tree.
+        all_environment_overrides: Optional environment variable mapping
+            forwarded to every git invocation and to the preflight rerun.
+
+    Returns:
+        Zero on success. Non-zero on the first failing git write or on a
+        non-zero preflight rerun exit code.
+
+    Raises:
+        RuntimeError: When a git read exits non-zero with non-empty stderr.
+    """
     local_hooks_path_values = list_local_core_hooks_path_values(
         repository_root,
         all_environment_overrides,