claude-dev-env 2.36.0 → 4.1.0

package/.agents/skills/syncing-submodules/scripts/test_submodule_sync.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPT_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPT_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIRECTORY))
+
+import submodule_sync
+from submodule_sync_constants.config.constants import (
+    GH_COMMAND_TIMEOUT_SECONDS,
+    GIT_COMMAND_TIMEOUT_SECONDS,
+)
+
+
+def _build_git_environment() -> dict[str, str]:
+    return {
+        each_name: each_content
+        for each_name, each_content in os.environ.items()
+        if not each_name.upper().startswith("GIT_")
+    }
+
+
+def _run_fixture_git(
+    repository_path: Path,
+    *all_arguments: str,
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *all_arguments],
+        cwd=repository_path,
+        check=False,
+        capture_output=True,
+        text=True,
+        env=_build_git_environment(),
+        timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+    )
+
+
+def _require_fixture_git(repository_path: Path, *all_arguments: str) -> str:
+    completed_process = _run_fixture_git(repository_path, *all_arguments)
+    assert completed_process.returncode == 0, completed_process.stderr
+    return completed_process.stdout.strip()
+
+
+def _configure_fixture_identity(repository_path: Path) -> None:
+    _require_fixture_git(repository_path, "config", "user.name", "Fixture User")
+    _require_fixture_git(
+        repository_path,
+        "config",
+        "user.email",
+        "fixture@example.invalid",
+    )
+    _require_fixture_git(repository_path, "config", "commit.gpgsign", "false")
+
+
+def _initialize_fixture_repository(repository_path: Path) -> None:
+    repository_path.mkdir(parents=True)
+    _require_fixture_git(repository_path, "init", "-b", "main")
+    _configure_fixture_identity(repository_path)
+
+
+def _create_submodule_fixture(tmp_path: Path) -> tuple[Path, Path]:
+    source_repository = tmp_path / "source-repository"
+    parent_repository = tmp_path / "parent-repository"
+    _initialize_fixture_repository(source_repository)
+    (source_repository / "README.md").write_text("source\n", encoding="utf-8")
+    _require_fixture_git(source_repository, "add", "README.md")
+    _require_fixture_git(source_repository, "commit", "-m", "Create source")
+    _initialize_fixture_repository(parent_repository)
+    (parent_repository / "README.md").write_text("parent\n", encoding="utf-8")
+    _require_fixture_git(parent_repository, "add", "README.md")
+    _require_fixture_git(parent_repository, "commit", "-m", "Create parent")
+    _require_fixture_git(
+        parent_repository,
+        "-c",
+        "protocol.file.allow=always",
+        "submodule",
+        "add",
+        str(source_repository),
+        "nested/sub[module]",
+    )
+    _require_fixture_git(parent_repository, "commit", "-am", "Add submodule")
+    submodule_repository = parent_repository / "nested" / "sub[module]"
+    _configure_fixture_identity(submodule_repository)
+    return parent_repository, submodule_repository
+
+
+def _commit_child_change(submodule_repository: Path) -> str:
+    (submodule_repository / "change.txt").write_text("change\n", encoding="utf-8")
+    _require_fixture_git(submodule_repository, "add", "change.txt")
+    _require_fixture_git(submodule_repository, "commit", "-m", "Record child change")
+    return _require_fixture_git(submodule_repository, "rev-parse", "HEAD")
+
+
+def _assert_parent_pointer_commit(
+    parent_repository: Path,
+    child_commit_hash: str,
+) -> None:
+    recorded_pointer = _require_fixture_git(
+        parent_repository,
+        "rev-parse",
+        "HEAD:nested/sub[module]",
+    )
+    changed_path = _require_fixture_git(
+        parent_repository,
+        "diff",
+        "HEAD^",
+        "HEAD",
+        "--name-only",
+    )
+    parent_commit_body = _require_fixture_git(
+        parent_repository,
+        "log",
+        "-1",
+        "--pretty=%B",
+    )
+    assert recorded_pointer == child_commit_hash
+    assert changed_path == "nested/sub[module]"
+    assert "Submodule commit: Record child change" in parent_commit_body
+    assert "Co-Authored-By" not in parent_commit_body
+
+
+def test_sync_updates_bracketed_pointer_and_preserves_staged_path(
+    tmp_path: Path,
+) -> None:
+    parent_repository, submodule_repository = _create_submodule_fixture(tmp_path)
+    staged_note_path = parent_repository / "staged-note.txt"
+    staged_note_path.write_text("keep staged\n", encoding="utf-8")
+    _require_fixture_git(parent_repository, "add", "staged-note.txt")
+    child_commit_hash = _commit_child_change(submodule_repository)
+
+    sync_report = submodule_sync.sync_repository(submodule_repository)
+
+    assert sync_report.status is submodule_sync.SyncStatus.UPDATED
+    assert sync_report.commit == child_commit_hash
+    assert sync_report.submodule_path == "nested/sub[module]"
+    assert (
+        _require_fixture_git(parent_repository, "status", "--short")
+        == "A  staged-note.txt"
+    )
+    _assert_parent_pointer_commit(parent_repository, child_commit_hash)
+
+
+def test_second_sync_is_unchanged_without_new_commit(tmp_path: Path) -> None:
+    parent_repository, submodule_repository = _create_submodule_fixture(tmp_path)
+    _commit_child_change(submodule_repository)
+
+    first_report = submodule_sync.sync_repository(submodule_repository)
+    parent_commit = _require_fixture_git(parent_repository, "rev-parse", "HEAD")
+    second_report = submodule_sync.sync_repository(submodule_repository)
+
+    assert first_report.status is submodule_sync.SyncStatus.UPDATED
+    assert second_report.status is submodule_sync.SyncStatus.UNCHANGED
+    assert second_report.parent_commit == parent_commit
+    assert _require_fixture_git(parent_repository, "rev-parse", "HEAD") == parent_commit
+
+
+def test_standalone_repository_is_a_noop(tmp_path: Path) -> None:
+    standalone_repository = tmp_path / "standalone"
+    _initialize_fixture_repository(standalone_repository)
+    (standalone_repository / "note.txt").write_text("unchanged\n", encoding="utf-8")
+    _require_fixture_git(standalone_repository, "add", "note.txt")
+    before_status = _require_fixture_git(standalone_repository, "status", "--short")
+
+    sync_report = submodule_sync.sync_repository(standalone_repository)
+
+    assert sync_report.status is submodule_sync.SyncStatus.NOT_SUBMODULE
+    assert sync_report.repository == standalone_repository.resolve().as_posix()
+    assert (
+        _require_fixture_git(standalone_repository, "status", "--short")
+        == before_status
+    )
+
+
+@pytest.mark.parametrize(
+    ("failed_git_operation", "failure_exit_code"),
+    [("add", 1), ("diff", 2), ("commit", 1)],
+)
+def test_git_failures_return_error_status(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    failed_git_operation: str,
+    failure_exit_code: int,
+) -> None:
+    _, submodule_repository = _create_submodule_fixture(tmp_path)
+    _commit_child_change(submodule_repository)
+    original_execute_git = submodule_sync._execute_git
+
+    def fail_selected_operation(
+        all_arguments: tuple[str, ...],
+        cwd: Path,
+    ) -> subprocess.CompletedProcess[str]:
+        if all_arguments[0] == failed_git_operation:
+            return subprocess.CompletedProcess(
+                ["git", *all_arguments],
+                failure_exit_code,
+                "",
+                f"fatal: fixture {failed_git_operation} failure",
+            )
+        return original_execute_git(all_arguments, cwd)
+
+    monkeypatch.setattr(submodule_sync, "_execute_git", fail_selected_operation)
+    sync_report = submodule_sync.sync_repository(submodule_repository)
+
+    assert sync_report.status is submodule_sync.SyncStatus.ERROR
+    assert sync_report.diagnostic == f"fatal: fixture {failed_git_operation} failure"
+
+
+def test_inherited_git_dir_does_not_redirect_commands(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    unrelated_repository = tmp_path / "unrelated"
+    _initialize_fixture_repository(unrelated_repository)
+    parent_repository, submodule_repository = _create_submodule_fixture(tmp_path)
+    child_commit_hash = _commit_child_change(submodule_repository)
+    monkeypatch.setenv("GIT_DIR", str(unrelated_repository / ".git"))
+
+    sync_report = submodule_sync.sync_repository(submodule_repository)
+
+    assert sync_report.status is submodule_sync.SyncStatus.UPDATED
+    recorded_pointer = _require_fixture_git(
+        parent_repository,
+        "rev-parse",
+        "HEAD:nested/sub[module]",
+    )
+    assert recorded_pointer == child_commit_hash
+
+
+def test_pull_request_lookup_returns_url_on_success(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    completed_process = subprocess.CompletedProcess(
+        ["gh"],
+        0,
+        "https://github.com/example/repo/pull/1\n",
+        "",
+    )
+
+    def return_completed_process(
+        *all_arguments: object,
+        **all_keyword_arguments: object,
+    ) -> subprocess.CompletedProcess[str]:
+        return completed_process
+
+    monkeypatch.setattr(submodule_sync.subprocess, "run", return_completed_process)
+
+    assert submodule_sync.lookup_pull_request_url(tmp_path) == (
+        "https://github.com/example/repo/pull/1"
+    )
+
+
+@pytest.mark.parametrize(
+    "completed_process",
+    [
+        subprocess.CompletedProcess(["gh"], 1, "", "no pull request"),
+        subprocess.CompletedProcess(["gh"], 1, "", "auth failed"),
+        subprocess.CompletedProcess(["gh"], 0, "", ""),
+    ],
+)
+def test_pull_request_lookup_soft_failures_return_none(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    completed_process: subprocess.CompletedProcess[str],
+) -> None:
+    def return_completed_process(
+        *all_arguments: object,
+        **all_keyword_arguments: object,
+    ) -> subprocess.CompletedProcess[str]:
+        return completed_process
+
+    monkeypatch.setattr(submodule_sync.subprocess, "run", return_completed_process)
+
+    assert submodule_sync.lookup_pull_request_url(tmp_path) is None
+
+
+@pytest.mark.parametrize(
+    "lookup_exception",
+    [
+        FileNotFoundError(),
+        subprocess.TimeoutExpired("gh", GH_COMMAND_TIMEOUT_SECONDS),
+    ],
+)
+def test_pull_request_lookup_unavailable_returns_none(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    lookup_exception: Exception,
+) -> None:
+    def raise_lookup_exception(
+        *all_arguments: object,
+        **all_keyword_arguments: object,
+    ) -> None:
+        raise lookup_exception
+
+    monkeypatch.setattr(submodule_sync.subprocess, "run", raise_lookup_exception)
+
+    assert submodule_sync.lookup_pull_request_url(tmp_path) is None

package/.agents/skills/syncing-submodules/scripts/test_sync_parent_pointer.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPT_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPT_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPT_DIRECTORY))
+
+import sync_parent_pointer
+from submodule_sync import SyncReport, SyncStatus
+
+
+def _read_single_json_line(
+    capsys: pytest.CaptureFixture[str],
+) -> tuple[dict[str, object], str]:
+    captured_streams = capsys.readouterr()
+    all_stdout_lines = captured_streams.out.splitlines()
+    assert len(all_stdout_lines) == 1
+    parsed_record = json.loads(all_stdout_lines[0])
+    assert isinstance(parsed_record, dict)
+    return parsed_record, captured_streams.err
+
+
+def test_invalid_repository_emits_one_json_record_and_diagnostic(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code = sync_parent_pointer.main(["--repository", str(tmp_path / "missing")])
+
+    sync_record, captured_error = _read_single_json_line(capsys)
+    assert exit_code == 1
+    assert sync_record["status"] == "error"
+    assert sync_record["diagnostic"]
+    assert "syncing-submodules:" in captured_error
+
+
+def test_invalid_arguments_emit_one_json_record_and_exit_two(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    exit_code = sync_parent_pointer.main(["--unknown"])
+
+    sync_record, captured_error = _read_single_json_line(capsys)
+    assert exit_code == 2
+    assert sync_record["status"] == "error"
+    assert "invalid command arguments" in str(sync_record["diagnostic"])
+    assert captured_error
+
+
+def test_success_emits_one_json_record(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    expected_report = SyncReport(
+        status=SyncStatus.NOT_SUBMODULE,
+        repository=tmp_path.as_posix(),
+    )
+
+    def return_expected_report(repository: Path) -> SyncReport:
+        return expected_report
+
+    monkeypatch.setattr(
+        sync_parent_pointer,
+        "sync_repository",
+        return_expected_report,
+    )
+    exit_code = sync_parent_pointer.main(["--repository", str(tmp_path)])
+
+    sync_record, captured_error = _read_single_json_line(capsys)
+    assert exit_code == 0
+    assert sync_record["status"] == "not_submodule"
+    assert captured_error == ""
+
+
+def test_native_post_commit_source_and_test_are_removed() -> None:
+    hook_directory = Path(__file__).resolve().parents[4] / "hooks" / "git-hooks"
+
+    assert not (hook_directory / "post_commit.py").exists()
+    assert not (hook_directory / "test_post_commit.py").exists()

package/.agents/skills/team-advisor/SKILL.md

@@ -16,23 +16,23 @@ One warm advisor at the strongest tier this session can reach. This session is t
 
 | Doc | Holds |
 |---|---|
-| [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight** — when to call, hard rule before first write, how to treat advice. Read this for every consult. |
-| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle** — session identity, host detect, model floor, warm-up, CLI fallback; its read map routes each moment to a `reference/` detail file. |
-| [`agents/session-advisor.md`](../../agents/session-advisor.md) | **Reply contract** — ENDORSE / CORRECTION / PLAN / STOP; SendMessage only. |
-| [`reference/advisor-docs-review.md`](reference/advisor-docs-review.md) | Anthropic advisor-tool source facts: measured effects, Sonnet steering, cost levers, failure modes. Background — read it when tuning the bind, not on every consult. |
+| [`docs/references/advisor-tool.md`](../../docs/references/advisor-tool.md) | **Consult cadence and weight.** When to call, the hard rule before first write, and how to treat advice. Read this for every consult. |
+| [`~/.claude/_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md) | **Bind and lifecycle.** Session identity, host detect, model floor, warm-up, CLI fallback. Its read map routes each moment to a `reference/` detail file. |
+| [`agents/session-advisor.md`](../../agents/session-advisor.md) | **Reply contract.** ENDORSE / CORRECTION / PLAN / STOP. SendMessage only. |
+| [`reference/advisor-docs-review.md`](reference/advisor-docs-review.md) | Anthropic advisor-tool source facts: measured effects, Sonnet steering, cost levers, failure modes. Background. Read it when tuning the bind, not on every consult. |
 
 ## Bind
 
 1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
-2. Claude: Fable first in-session at `ADVISOR_EFFORT` (default low). When Fable is out of usage, bind Sol at the same effort. Codex: Sol in-session. Third-party: headless Fable then Sol. When the host's walk fails, fail closed.
-3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); a native Sol subagent on Codex; one CLI `session_id` on a third-party host via the protocol Claude-chain.
+2. Claude: Fable first in-session at `ADVISOR_EFFORT` (default low). When Fable is out of usage, bind Astra at the same effort. Codex: Astra in-session. Third-party: headless Fable then Astra. When the host's walk fails, fail closed.
+3. Name: `team-advisor-agent` on Claude (Agent spawn of `session-advisor`); a native Astra subagent on Codex; one CLI `session_id` on a third-party host via the protocol Claude-chain or Astra helper.
 4. A Fable-tier spawn or re-spawn carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt (protocol warm-up; `fable_spawn_gate` requires it).
-5. Skip the multi-consumer "who you are" opener — sole consumer.
-6. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound Claude advisor issues ENDORSE / CORRECTION / PLAN / STOP.
+5. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
+6. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
-**GOTCHA (Cursor / ThirdParty + Sol):** when the walk reaches Sol or the user asks for Sol, first tool call is `python ~/.claude/_shared/advisor/scripts/codex_sol_advisor.py --bind --enable-sol --cwd <repo-root>` with the charter on stdin — not Agent/Task, not a probe-path search. Details: [`third-party-bind.md`](../../_shared/advisor/reference/third-party-bind.md) GOTCHA and [`sol-rung.md`](../../_shared/advisor/reference/sol-rung.md).
+**GOTCHA (Cursor / ThirdParty + Astra):** when the walk reaches Astra or the user asks for Astra, first tool call is `python ~/.claude/_shared/advisor/scripts/codex_astra_advisor.py --bind --enable-astra --cwd <repo-root>` with the charter on stdin. Do not use Agent or Task. Do not search for a probe path. Details: [`third-party-bind.md`](../../_shared/advisor/reference/third-party-bind.md) GOTCHA and [`astra-rung.md`](../../_shared/advisor/reference/astra-rung.md).
 
-Full walk, charter, consult packet, Sol routing, and drift re-bind live in the protocol read map and its authoritative `reference/` leaves.
+Full walk, charter, consult packet, Astra routing, and drift re-bind live in the protocol read map and its `reference/` files.
 
 ## Consult
 
@@ -44,6 +44,6 @@ Aim for two consults on a normal task: one after orientation and one after write
 
 ## Constraints
 
-- One bind per session; this session owns spawn, in-session Sol spawn, or CLI bind, drift re-bind, and shutdown.
+- One bind per session; this session owns spawn, in-session Astra spawn, or CLI bind, drift re-bind, and shutdown.
 - Bind at or above the protocol floor for this host.
 - The advisor only answers (messaging); the session runs tools and posts.

package/_shared/advisor/advisor-protocol.md

@@ -13,20 +13,20 @@ On Claude, continue with **Model floor** and the rest of this document.
 
 ## Read map
 
-The sections below hold the standing rules; open a reference file at the moment its row names.
+The sections below hold the standing rules. Open a reference file at the moment its row names.
 
 | Moment | Open |
 |---|---|
-| Naming the session identity | [`reference/identity.md`](reference/identity.md) — Claude, Codex, or neither |
-| Binding on a Claude host | [`reference/warm-up.md`](reference/warm-up.md) — spawn fields, Fable token, charter |
-| Binding on a Codex host | [`reference/identity.md`](reference/identity.md) — in-session Sol spawn |
-| Binding from a third-party host | [`reference/third-party-bind.md`](reference/third-party-bind.md) — CLI bind steps, fail-closed rule |
-| Fable is out of usage | [`reference/sol-rung.md`](reference/sol-rung.md) — Sol fallback at shared effort |
-| Composing a consult | [`reference/consult-format.md`](reference/consult-format.md) — packet, new-evidence and report-back rules |
-| Assembling an executor spawn prompt | [`reference/advisor-block.md`](reference/advisor-block.md) — the paste parts |
-| Advisor drifts, dies, or the task pivots | [`reference/lifecycle.md`](reference/lifecycle.md) — re-spawn and re-bind steps |
-| Logging or checking a bind walk | [`reference/spawn-walk-log.md`](reference/spawn-walk-log.md) — record shape, validator |
-| Any CLI call to a Claude advisor | [`reference/cli-chain.md`](reference/cli-chain.md) — runner modes, alias table, resume |
+| Naming the session identity | [`reference/identity.md`](reference/identity.md): Claude, Codex, or neither |
+| Binding on a Claude host | [`reference/warm-up.md`](reference/warm-up.md): spawn fields, Fable token, charter |
+| Binding on a Codex host | [`reference/identity.md`](reference/identity.md): in-session Astra spawn |
+| Binding from a third-party host | [`reference/third-party-bind.md`](reference/third-party-bind.md): CLI bind steps, fail-closed rule |
+| Fable is out of usage | [`reference/astra-rung.md`](reference/astra-rung.md): Astra fallback at shared effort |
+| Composing a consult | [`reference/consult-format.md`](reference/consult-format.md): packet, new-evidence and report-back rules |
+| Assembling an executor spawn prompt | [`reference/advisor-block.md`](reference/advisor-block.md): the paste parts |
+| Advisor drifts, dies, or the task pivots | [`reference/lifecycle.md`](reference/lifecycle.md): re-spawn and re-bind steps |
+| Logging or checking a bind walk | [`reference/spawn-walk-log.md`](reference/spawn-walk-log.md): record shape, validator |
+| Any CLI call to a Claude advisor | [`reference/cli-chain.md`](reference/cli-chain.md): runner modes, alias table, resume |
 
 ## Host profiles
 
@@ -42,95 +42,95 @@ Session identity:
 Mechanical override for scripts:
 
 1. `ADVISOR_HOST_PROFILE=ThirdParty` or `=Claude` or `=Codex` (explicit override; any letter case).
-2. `THIRD_PARTY=1` (or `true` / `yes` / `on`) — a third-party (non-Claude) harness.
+2. `THIRD_PARTY=1` (or `true` / `yes` / `on`) selects a third-party (non-Claude) harness.
 3. Default: Claude.
 
-### Shared effort — any host
+### Shared effort, any host
 
-Fable and Sol both read `ADVISOR_EFFORT` (`low`, `medium`, `high`, `xhigh`, `max`). The default is `low`.
-Pass `--effort <level>` on the Sol helper to set effort for that Sol run.
+Fable and Astra both read `ADVISOR_EFFORT` (`low`, `medium`, `high`, `xhigh`, `max`). The default is `low`.
+Pass `--effort <level>` on the Astra helper to set effort for that Astra run.
 Pass `--effort <level>` on the Claude CLI bind for Fable. An unset or unrecognized value uses `low`.
 
-### Sol rung
+### Astra rung
 
-On Claude and ThirdParty: when Fable is out of usage, bind Sol through the Codex helper.
-Open that attempt with `ADVISOR_SOL=1` (or `true` / `yes` / `on`) in the environment, or pass `--enable-sol` on the helper invocation.
+On Claude and ThirdParty: when Fable is out of usage, bind Astra through the Codex helper.
+Open that attempt with `ADVISOR_ASTRA=1` (or `true` / `yes` / `on`) in the environment, or pass `--enable-astra` on the helper invocation.
 Flag off both ways: fail closed when Fable did not bind.
-Flag on: run the Codex preflight and bind per [`reference/sol-rung.md`](reference/sol-rung.md); a failed preflight fails closed when Fable did not bind.
+Flag on: run the Codex preflight and bind per [`reference/astra-rung.md`](reference/astra-rung.md); a failed preflight fails closed when Fable did not bind.
 
-On Codex: Sol is the in-session default. The `ADVISOR_SOL` flag is not required. Fail closed when that spawn does not bind.
+On Codex: Astra is the in-session default. The `ADVISOR_ASTRA` flag is not required. Fail closed when that spawn does not bind.
 
 ### Claude host
 
-Use the **Model floor** ladder below (Fable first, then Sol when Fable is out of usage).
-Warm-up spawns `subagent_type: session-advisor` via the Agent tool; consults go through `SendMessage` to that warm agent.
+Use the **Model floor** ladder below (Fable first, then Astra when Fable is out of usage).
+Warm-up spawns `subagent_type: session-advisor` via the Agent tool for Fable; consults go through `SendMessage` to that warm agent. Astra uses the Codex helper.
 Assemble and paste each executor's Advisor block per the **Advisor block** section.
 
 ### Codex host
 
-Spawn a native in-session Sol subagent at `resolve_codex_model_id("Sol")`.
-Walk `candidate_tiers = ["Sol"]`. Record `{tier: "Sol", result: "spawned"}` on success.
-**Fail closed:** when Sol does not bind, set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**.
-Do not walk Fable on a Codex host. Consults stay in-session with that Sol subagent.
+Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")`.
+Walk `candidate_tiers = ["Astra"]`. Record `{tier: "Astra", result: "spawned"}` on success.
+**Fail closed:** when Astra does not bind, set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**.
+Do not walk Fable on a Codex host. Consults stay in-session with that Astra subagent.
 Assemble and paste each executor's Advisor block per the **Advisor block** section.
 
 ### Third-party host
 
 On a third-party (non-Claude, non-Codex) harness, the shared CLI Claude-chain is the one path to a Claude advisor: bind Fable through it, per [`reference/third-party-bind.md`](reference/third-party-bind.md).
 The bound Claude session is the advisor; this third-party session stays the executor.
-Walk `candidate_tiers = ["Fable"]`. When Fable is out of usage, the sol rung binds after Fable (`candidate_tiers = ["Fable", "Sol"]`).
-**Cursor Sol first shot:** when the walk reaches Sol (or the user asks for Sol), bind through `codex_sol_advisor.py --bind --enable-sol` on the first tool call (see the GOTCHA in [`reference/third-party-bind.md`](reference/third-party-bind.md)) — not the Agent tool, and not a probe-path hunt.
-**Fail closed:** when every candidate fails, set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop** — ENDORSE / CORRECTION / PLAN / STOP come only from a bound advisor.
+Walk `candidate_tiers = ["Fable"]`. When Fable is out of usage, the Astra rung binds after Fable (`candidate_tiers = ["Fable", "Astra"]`).
+**Cursor Astra first shot:** when the walk reaches Astra (or the user asks for Astra), bind through `codex_astra_advisor.py --bind --enable-astra` on the first tool call (see the GOTCHA in [`reference/third-party-bind.md`](reference/third-party-bind.md)). Do not use the Agent tool, and do not hunt a probe path.
+**Fail closed:** when every candidate fails, set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop**. ENDORSE / CORRECTION / PLAN / STOP come only from a bound advisor.
 Executors report to the orchestrating session; that session consults the bound advisor and relays the four-signal reply.
 
 ## Model floor
 
-On Claude and ThirdParty the advisor ladder is `Fable` first, then sol (flag-gated, Codex CLI) when Fable is out of usage.
-On Codex the walk is Sol only, in-session.
+On Claude and ThirdParty the advisor ladder is `Fable` first, then Astra (flag-gated, Codex CLI) when Fable is out of usage.
+On Codex the walk is Astra only, in-session.
 Opus is not an advisor candidate. `Sonnet` and `Haiku` are executor tiers only.
 Consumer `own_tier` is recorded on the spawn-walk log; it does not add Opus to the advisor walk.
 Tier names are canonical Title Case; the validator accepts any letter case and normalizes to Title Case.
-Try binds top-down. Each try resolves its candidate tier to the short model alias via the tier-to-alias map in [`reference/cli-chain.md`](reference/cli-chain.md).
-The advisor is created at `selected_tier` — the first ladder tier that binds.
-When Fable fails on a Claude host, try Sol if the flag is on, else fail closed. The CLI chain is the Fable bind path on a third-party host and the Claude-host fallback for Fable; it does not bind Opus as advisor.
-On a Codex host a failed Sol spawn fails closed per **Host profiles → Codex host**.
-On a third-party host the CLI chain is already the primary path, so a failed Fable (and Sol, when enabled) walk fails closed per **Host profiles → Third-party host**.
+Try binds top-down. Fable resolves to the short model alias in [`reference/cli-chain.md`](reference/cli-chain.md); Astra resolves through `resolve_codex_model_id("Astra")` to `gpt-6-astra`.
+The advisor is created at `selected_tier`, the first ladder tier that binds.
+When Fable fails on a Claude host, try Astra if the flag is on, else fail closed. The CLI chain is the Fable bind path on a third-party host and the Claude-host fallback for Fable; it does not bind Opus as advisor.
+On a Codex host a failed Astra spawn fails closed per **Host profiles → Codex host**.
+On a third-party host the CLI chain is already the primary path, so a failed Fable (and Astra, when enabled) walk fails closed per **Host profiles → Third-party host**.
 
 Emit a structured spawn-walk log so the walk can be checked mechanically: [`reference/spawn-walk-log.md`](reference/spawn-walk-log.md).
 The validator checks ladder shape only; host policy sits on top.
 
-**Equal-tier pairings.** Bind Fable for an independent second pass on irreversible or security-sensitive work. The advisor is Fable or Sol.
+**Equal-tier pairings.** Bind Fable for an independent second pass on irreversible or security-sensitive work. The advisor is Fable or Astra.
 
 ## Warm-up (once per session)
 
-On a **Claude host**, walk the candidate tiers top-down, spawning `session-advisor` in the background at each candidate's alias with the charter as its prompt, stopping at the first successful spawn.
-A **Fable**-tier try carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt — `hooks/blocking/fable_spawn_gate.py` denies a Fable-tier spawn without it.
+On a **Claude host**, spawn `session-advisor` at the Fable alias with the charter as its prompt. When Fable is out of usage and the Astra rung is open, bind Astra through the Codex helper instead.
+A **Fable**-tier try carries the exact token `FABLE-SPAWN-AUTHORIZED` in its prompt. `hooks/blocking/fable_spawn_gate.py` denies a Fable-tier spawn without it.
 Full spawn fields and the charter template: [`reference/warm-up.md`](reference/warm-up.md).
 
-On a **Codex host**, spawn a native in-session Sol subagent with the same charter. Bind fields: [`reference/identity.md`](reference/identity.md) and [`reference/warm-up.md`](reference/warm-up.md).
+On a **Codex host**, spawn a native in-session Astra subagent with the same charter. Bind fields: [`reference/identity.md`](reference/identity.md) and [`reference/warm-up.md`](reference/warm-up.md).
 
-On a **third-party host**, bind per [`reference/third-party-bind.md`](reference/third-party-bind.md) and charter the CLI session with the same charter — the reply contract is the same, and consults travel through the CLI runner.
+On a **third-party host**, bind per [`reference/third-party-bind.md`](reference/third-party-bind.md) and charter the CLI session with the same charter. The reply contract is the same, and consults travel through the CLI runner.
 
 ## Consulting the warm agent
 
-Send a consult at the trigger points `docs/references/advisor-tool.md` **When to call** defines — plan lock-in, believed completion, hard-to-reverse actions, repeated failure or stalled progress, and reconsidered approach.
+Send a consult at the trigger points `docs/references/advisor-tool.md` **When to call** defines: plan lock-in, believed completion, hard-to-reverse actions, repeated failure or stalled progress, and reconsidered approach.
 The paste parts in [`reference/advisor-block.md`](reference/advisor-block.md) restate them for executors.
 
-Each consult carries the sender's identity and assignment, the delta since the last consult, the live decision or blocker, and the paths or excerpts needed to answer well — full packet shape plus the new-evidence and report-back rules: [`reference/consult-format.md`](reference/consult-format.md).
+Each consult carries the sender's identity and assignment, the delta since the last consult, the live decision or blocker, and the paths or excerpts needed to answer well. Full packet shape plus the new-evidence and report-back rules: [`reference/consult-format.md`](reference/consult-format.md).
 Consult briefs embed the `docs/references/advisor-tool.md` **Brevity cue** line, sized per that section.
 
-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 CORRECTION names a wrong step or a risk worth closing. Address it before treating the plan or the work as done.
 Route a STOP, or an unreachable advisor, upward per [`reference/consult-format.md`](reference/consult-format.md).
 
-## Advisor block — assemble and paste into every executor spawn prompt
+## Advisor block
 
-Assemble each executor's block from the parts in [`reference/advisor-block.md`](reference/advisor-block.md), in order: one transport preamble picked by host profile, then the shared core, then — for an executor at Sonnet or below — the weak-executor add-on.
+Assemble each executor's block from the parts in [`reference/advisor-block.md`](reference/advisor-block.md), in order: one transport preamble picked by host profile, then the shared core, then the weak-executor add-on for an executor at Sonnet or below.
 Paste the assembled block at the **top** of the spawn prompt, ahead of any other sentence that mentions the advisor.
-The assembled block is self-contained — the executor receives this text alone.
+The assembled block is self-contained. The executor receives this text alone.
 
 ## Lifecycle ownership
 
-The session that binds the advisor owns its whole lifecycle — first bind, drift re-spawn or re-bind, and shutdown; every other consumer reaches the advisor by message alone.
+The session that binds the advisor owns its whole lifecycle: first bind, drift re-spawn or re-bind, and shutdown. Every other consumer reaches the advisor by message alone.
 Drift signals and the per-host re-spawn / re-bind steps: [`reference/lifecycle.md`](reference/lifecycle.md).
 
 ## CLI chain
@@ -140,14 +140,14 @@ Modes and failover, the tier-to-alias table, brief piping, and `--resume` sessio
 
 **Third-party host:** the primary bind and consult path; the walk order and fail-closed rule live in [`reference/third-party-bind.md`](reference/third-party-bind.md).
 
-**Codex host:** do not use this runner as the primary path. Sol binds in-session.
+**Codex host:** do not use this runner as the primary path. Astra binds in-session.
 
 **Claude host:** fall back to this runner exactly when one of these holds:
-- The Agent-tool spawn errors at every candidate tier down to the floor — the tool itself is unavailable.
+- The Agent-tool spawn errors at every candidate tier down to the floor. The tool itself is unavailable.
 - `SendMessage` to the shared advisor errors, or draws no reply within the bound in `ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS` (120) in `$HOME/.claude/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py`, and a re-spawn also fails.
 - The running session is itself a subagent barred from spawning further agents.
 
 ## State the mechanism
 
-One warm agent, addressed by name, whose transcript accumulates across consults — each consult sends only the delta since the last one.
+One warm agent, addressed by name, whose transcript accumulates across consults. Each consult sends only the delta since the last one.
 A consuming skill's own text states this mechanism; a token or cost saving becomes a claim only after a measured comparison against cold spawns.