claude-dev-env 8.38.2 → 8.39.0

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

@@ -29,10 +29,10 @@ The frozen process env is only a fallback when that disk read fails (logged once
 A probe error does not waive the gate; the live GitHub checks still run.
 
 The Codex gate is conditional-required: it demands
-``codex_clean_at == current_head`` only when the Codex account picker
-(``scripts/codex_account_choice.py choose``) answers the ``normal`` tier, so
+``codex_clean_at == current_head`` only when the account broker
+(``scripts/account_broker.py choose --product codex``) answers the ``normal`` tier, so
 one signed-in account has room for a review. A ``luna`` or ``wait`` answer, an
-unreadable picker, the codex token, or ``codex_down`` never blocks ready.
+unreadable broker, the codex token, or ``codex_down`` never blocks ready.
 """
 
 from __future__ import annotations
@@ -64,11 +64,12 @@ from check_convergence_thread_gates import (
     _count_unresolved_bot_threads,
 )
 from pr_converge_scripts_constants.convergence_gate_constants import (
-    ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS,
+    ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS,
+    ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES,
     BUGBOT_DOWN_BYPASS_NOTE,
     CLAUDE_JOB_DIR_ENV_VAR_NAME,
     CODEX_ACCOUNT_PICK_TIMEOUT_SECONDS,
-    CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND,
+    CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND,
     CODEX_BYPASS_DETAIL,
     CODEX_CLEAN_AT_STATE_KEY,
     CODEX_CLEAN_DETAIL_TEMPLATE,
@@ -344,16 +345,16 @@ def _evaluate_codex_clean(
 
     ::
 
-        clean stamp on head                  -> pass  (picker never runs)
+        clean stamp on head                  -> pass  (broker never runs)
         no stamp, tier luna, wait, or None   -> skip  (never blocks)
         no stamp, tier normal                -> fail
 
-    A stamp on the current HEAD settles the gate on its own, so the picker
-    stays behind it: the picker starts one Codex app server per account, and
+    A stamp on the current HEAD settles the gate on its own, so the broker
+    stays behind it: the broker starts one Codex app server per account, and
     the common already-clean tick has no reason to pay for them.
 
     Args:
-        read_codex_tier: Returns the picker's tier, or None when the picker cannot say.
+        read_codex_tier: Returns the broker's tier, or None when the broker cannot say.
         codex_clean_at: HEAD SHA where Codex last reported clean, or None.
         head_sha: Current PR HEAD commit SHA.
 
@@ -367,20 +368,22 @@ def _evaluate_codex_clean(
     return False, CODEX_MISSING_CLEAN_DETAIL_TEMPLATE % _short_sha(head_sha)
 
 
-def _codex_account_picker_path() -> Path:
-    """Return the installed Codex account picker beside this shared tree."""
+def _codex_account_broker_path() -> Path:
+    """Return the installed account broker beside this shared tree."""
     shared_root = Path(__file__).resolve().parents[SHARED_PACKAGE_ROOT_PARENT_INDEX]
-    return shared_root.joinpath(*ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS)
+    return shared_root.joinpath(*ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS)
 
 
 def _read_codex_tier() -> str | None:
-    """Ask the Codex account picker which tier a review runs on, or None when it cannot say."""
+    """Ask the account broker which tier a review runs on, or None when it cannot say."""
     try:
         completed = subprocess.run(
             [
                 sys.executable,
-                str(_codex_account_picker_path()),
-                CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND,
+                str(_codex_account_broker_path()),
+                CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND,
+                "--product",
+                "codex",
             ],
             capture_output=True,
             text=True,
@@ -390,9 +393,12 @@ def _read_codex_tier() -> str | None:
         answer = json.loads(completed.stdout)
     except (OSError, subprocess.SubprocessError, json.JSONDecodeError):
         return None
-    if completed.returncode != 0 or not isinstance(answer, dict):
+    if completed.returncode not in ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES or not isinstance(answer, dict):
         return None
-    tier = answer.get(CODEX_TIER_KEY)
+    decision = answer.get("decision")
+    if not isinstance(decision, dict):
+        return None
+    tier = decision.get(CODEX_TIER_KEY)
     return tier if isinstance(tier, str) else None
 
 

package/_shared/pr-loop/scripts/pr_converge_scripts_constants/convergence_gate_constants.py

@@ -69,11 +69,12 @@ CODEX_CLEAN_AT_STATE_KEY: str = "codex_clean_at"
 CODEX_DOWN_STATE_KEY: str = "codex_down"
 MINIMUM_ABBREVIATED_SHA_LENGTH: int = 7
 SHARED_PACKAGE_ROOT_PARENT_INDEX: int = 3
-ALL_CODEX_ACCOUNT_PICKER_RELATIVE_PARTS: tuple[str, ...] = (
+ALL_CODEX_ACCOUNT_BROKER_RELATIVE_PARTS: tuple[str, ...] = (
     "scripts",
-    "codex_account_choice.py",
+    "account_broker.py",
 )
-CODEX_ACCOUNT_PICKER_CHOOSE_COMMAND: str = "choose"
+CODEX_ACCOUNT_BROKER_CHOOSE_COMMAND: str = "choose"
 CODEX_ACCOUNT_PICK_TIMEOUT_SECONDS: float = 150.0
 CODEX_TIER_KEY: str = "tier"
+ALL_CODEX_BROKER_ACCEPTED_EXIT_CODES: tuple[int, ...] = (0, 3)
 CODEX_TIER_NORMAL: str = "normal"

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

@@ -1,7 +1,7 @@
 """Fixture-driven tests for the conditional Codex convergence gate.
 
 Covers: required-and-clean, required-and-dirty, skipped-by-tier,
-skipped-by-token, skipped-by-down, and the read of the Codex account picker's
+skipped-by-token, skipped-by-down, and the read of the account broker's
 ``choose`` answer. The required tier comes from ``CODEX_TIER_NORMAL``.
 """
 
@@ -117,15 +117,15 @@ def should_pass_when_codex_required_and_clean(
     assert "All pre-conditions met" in captured
 
 
-def should_pass_without_running_the_picker_when_the_clean_stamp_is_on_head(
+def test_should_pass_without_running_the_broker_when_the_clean_stamp_is_on_head(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    def _picker_that_must_not_run() -> str | None:
+    def _broker_that_must_not_run() -> str | None:
         raise AssertionError(
-            "the Codex account picker must not run when codex_clean_at is on HEAD"
+            "the account broker must not run when codex_clean_at is on HEAD"
         )
 
-    monkeypatch.setattr(check_convergence, "_read_codex_tier", _picker_that_must_not_run)
+    monkeypatch.setattr(check_convergence, "_read_codex_tier", _broker_that_must_not_run)
 
     is_passed, detail = check_convergence._evaluate_codex_clean(
         read_codex_tier=check_convergence._read_codex_tier,
@@ -228,7 +228,7 @@ def should_fail_when_codex_required_and_dirty(
 
 
 @pytest.mark.parametrize("tier_without_room", ALL_TIERS_WITHOUT_ROOM_FOR_REVIEW)
-def should_skip_when_the_picker_names_no_account_with_room_for_review(
+def test_should_skip_when_the_broker_names_no_account_with_room_for_review(
     tier_without_room: str, tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
     fixture_path = _write_fixture(
@@ -513,47 +513,86 @@ def should_accept_codex_clean_at_flag_in_parsed_arguments() -> None:
     assert arguments.codex_clean_at == HEAD_SHA
 
 
-def _install_fake_picker(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, picker_source: str
+def _install_fake_broker(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, broker_source: str
 ) -> None:
-    picker_path = tmp_path / "codex_account_choice.py"
-    picker_path.write_text(picker_source, encoding="utf-8")
-    monkeypatch.setattr(check_convergence, "_codex_account_picker_path", lambda: picker_path)
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(broker_source, encoding="utf-8")
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
 
 
-def should_read_the_tier_the_picker_chooses(
+def test_should_read_normal_tier_from_broker_decision(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fake_picker(
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(
+        "import json, sys\n"
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'normal', 'reason': 'room'}, 'accounts': []}))\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
+
+    assert check_convergence._read_codex_tier() == CODEX_TIER_NORMAL
+
+
+def test_should_read_wait_tier_from_broker_exit_three(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    broker_path = tmp_path / "account_broker.py"
+    broker_path.write_text(
+        "import json, sys\n"
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'wait', 'reason': 'no room'}, 'accounts': []}))\n"
+        "sys.exit(3)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(check_convergence, "_codex_account_broker_path", lambda: broker_path)
+
+    assert check_convergence._read_codex_tier() == "wait"
+
+    passed, detail = check_convergence._evaluate_codex_clean(
+        read_codex_tier=check_convergence._read_codex_tier,
+        codex_clean_at=None,
+        head_sha=HEAD_SHA,
+    )
+    assert passed
+    assert "skipped" in detail
+
+
+def test_should_read_the_tier_the_broker_chooses(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install_fake_broker(
         tmp_path,
         monkeypatch,
         "import json, sys\n"
-        "assert sys.argv[1:] == ['choose']\n"
-        "print(json.dumps({'tier': 'normal', 'account': 'codex-2'}))\n",
+        "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
+        "print(json.dumps({'decision': {'tier': 'normal', 'account': 'codex-2'}, 'accounts': []}))\n",
     )
 
     assert check_convergence._read_codex_tier() == CODEX_TIER_NORMAL
 
 
 @pytest.mark.parametrize(
-    "picker_source",
+    "broker_source",
     [
-        "import sys\nprint('{\"tier\": \"normal\"}')\nsys.exit(1)\n",
+        "import sys\nprint('{\"decision\": {\"tier\": \"normal\"}}')\nsys.exit(1)\n",
         "print('not json')\n",
         "print('[\"normal\"]')\n",
-        "print('{\"tier\": 1}')\n",
+        "print('{\"decision\": {\"tier\": 1}}')\n",
     ],
 )
-def should_read_no_tier_when_the_picker_fails_or_answers_out_of_shape(
-    picker_source: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+def test_should_read_no_tier_when_the_broker_fails_or_answers_out_of_shape(
+    broker_source: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    _install_fake_picker(tmp_path, monkeypatch, picker_source)
+    _install_fake_broker(tmp_path, monkeypatch, broker_source)
 
     assert check_convergence._read_codex_tier() is None
 
 
-def should_locate_the_packaged_codex_account_picker() -> None:
-    picker_path = check_convergence._codex_account_picker_path()
+def test_should_locate_the_packaged_codex_account_broker() -> None:
+    broker_path = check_convergence._codex_account_broker_path()
 
-    assert picker_path.name == "codex_account_choice.py"
-    assert picker_path.is_file()
+    assert broker_path.name == "account_broker.py"
+    assert broker_path.is_file()

package/docs/codex-accounts.md

@@ -1,15 +1,16 @@
 # Codex accounts
 
-The codex_account_choice picker spreads agent work across the Codex accounts
-on one machine. Each account signs in under its own Codex home, and every home
+The account broker assigns agent work across the Codex accounts.
+Each account signs in under its own Codex home, and every home
 shares the same Codex setup: config, rules, skills, plugins, prompts and agents.
-A job asks the picker which account to use.
+A job asks the broker which account to use.
 
 ## Pieces
 
 | File | What it does |
 |---|---|
-| `scripts/codex_account_choice.py` | `choose` names the account and tier a job runs on, `check` tells a running job whether its account is still above a floor, `sync` links the shared setup into every account's home, `setup` and `install` write one launcher per account |
+| `scripts/account_broker.py` | `choose --product codex` names the account and tier a job runs on; `check --product codex` reports whether any account has room |
+| `scripts/codex_account_choice.py` | `sync` links the shared setup into every account's home; `setup` and `install` write one launcher per account |
 | `scripts/codex_account_meters.py` | Reads one account's rate-limit windows through `codex app-server` with `CODEX_HOME` set to that account's home |
 | `scripts/dev_env_scripts_constants/codex_account_constants.py` | The fallback account names, the roster variable and file, the launcher template, the shared entry names, the 10% bar, the 1% Luna stop, and the 20% 5-hour floor for Luna |
 
@@ -21,8 +22,8 @@ The account roster names the accounts and their order. It comes from the
 in `account-launchers.json` under the profiles root. When neither exists, the
 accounts are `codex-1`, `codex-2`, `codex-3` and `codex-4`.
 
-`choose`, `sync` and `check` all work on that list, in that order. `check`
-accepts only a name on it. Each account's home is `~/.codex-profiles/<name>`, or
+The broker's `choose` and `check` commands and the setup commands use that list.
+Each account's home is `~/.codex-profiles/<name>`, or
 `<name>` under `CODEX_PROFILES_ROOT` when set. `~/.codex` holds the shared setup
 and is never an account. A name uses letters, digits, hyphens or underscores.
 `main`, `wait` and the Windows device names are refused.
@@ -83,50 +84,45 @@ folder under the profiles root stays, with its `auth.json`, so typing the name
 again restores it. A blank first line empties the roster and moves every launcher
 aside.
 
-`check <name>` reads a saved name the same way:
-
-```
-python packages/claude-dev-env/scripts/codex_account_choice.py check alpha --floor 1
-```
-
 ## Which account a job uses
 
 Room is the smaller of an account's two windows: the 5-hour window and the week.
 
 | Condition | Answer |
 |---|---|
-| First account in order with more than 10% left | `normal` on that account |
-| No account over 10%, one or more over 1% | `luna` on the account with the most room, `stop_below_percent` 1 |
+| One or more accounts with more than 10% left | `normal` on the account with the most room |
+| No account over 10%, one or more over 1% | `luna` on the account with the most room |
 | An account that reports a 5-hour window, with under 20% of that window left | never takes `luna` |
-| No account over 1% | `wait`, naming the account whose blocking windows reset first |
-| Account not signed in, or its meter unread | skipped, with the reason in `accounts` |
+| No account over 1% | `wait`, naming the next reset when known |
+| A meter is unread | The account has `meters: null` in `accounts` |
 
 ```
-python packages/claude-dev-env/scripts/codex_account_choice.py choose
-{"tier": "normal", "account": "codex-1", "codex_home": "...\\codex-1", "percent_left": 62.0,
- "stop_below_percent": null, "reason": "codex-1 has 62% left", "accounts": [...]}
+python packages/claude-dev-env/scripts/account_broker.py choose --product codex
+{"decision": {"action": "run", "account": "codex-1", "home": "...\\codex-1",
+ "resets_at": null, "reason": "codex-1 has 62% left", "tier": "normal"},
+ "accounts": [{"name": "codex-1", "home": "...\\codex-1", "is_main": false,
+ "meters": {"session_percent_left": 62.0, "session_resets_at": null,
+ "weekly_percent_left": 70.0, "weekly_resets_at": null}}]}
 ```
 
-A job runs Codex with `CODEX_HOME` set to `codex_home`. On `luna`, the job runs
+A job runs Codex with `CODEX_HOME` set to `decision.home`. On `luna`, the job runs
 Luna and polls `check` between steps:
 
 ```
-python packages/claude-dev-env/scripts/codex_account_choice.py check codex-2 --floor 1
+python packages/claude-dev-env/scripts/account_broker.py check --product codex
 ```
 
-`check` exits 0 while the account has more than the floor left, and 3 once it has
-not or its meter is unread. The job stops on 3.
+`check` exits 3 while every account is below its floor, and 0 when an account
+has room. The job stops on 3. `choose` also exits 3 for `wait` and still prints
+the JSON answer.
 
 ## Shared callers
 
-Two scripts under `_shared` run `choose` by path. Each finds the picker at
-`scripts/codex_account_choice.py` in the directory that holds `_shared`. Once
-installed, that is `~/.claude/scripts/codex_account_choice.py`.
+Two scripts under `_shared` run `choose --product codex` by path. Each finds the
+broker at `scripts/account_broker.py` in the directory that holds `_shared`.
+Once installed, that is `~/.claude/scripts/account_broker.py`.
 
 | Caller | What it does with the answer |
 |---|---|
-| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed picker skips the Codex gate |
-| `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `codex_home` |
-
-Pass `--codex-path` when `codex` is off PATH. Without it the picker also tries
-the desktop install path under the user home.
+| `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed broker skips the Codex gate |
+| `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `decision.home` |

package/hooks/session/skill_loaded_reminder.py

@@ -1,15 +1,18 @@
 #!/usr/bin/env python3
-"""Hook that keeps poteto-mode loaded in every session, subagent and workflow helper.
+"""Hook that restores poteto-mode after compaction and loads it for helpers.
 
 ::
 
     Agent or Codex spawn_agent, skill not named -> prompt opens with "invoke poteto-mode"
     Workflow script helper starts               -> "invoke poteto-mode now"
-    context compacted mid-run                    -> "invoke poteto-mode again"
-    user turn, skill not loaded since compacting -> "invoke poteto-mode now"
-    user turn, skill already loaded              -> nothing
-
-A session that loaded the skill hears nothing more until a compaction drops it.
+    compact SessionStart, skill invoked before   -> "invoke the skill again"
+    compact SessionStart, no prior invocation
+    or transcript unavailable                    -> nothing
+    user turn, skill invoked then compacted      -> "invoke poteto-mode now"
+    user turn, skill loaded, never invoked,
+    or transcript unavailable                    -> nothing
+
+A session that invoked the skill hears nothing more until a compaction drops it.
 The hook prints its output and stops.
 """
 
@@ -116,66 +119,92 @@ def _is_loaded_after(all_entry_fields: dict[str, object], was_loaded: bool) -> b
     return was_loaded or _invokes_poteto_mode(all_entry_fields)
 
 
-def is_poteto_mode_loaded(all_transcript_lines: Iterable[str]) -> bool:
-    """Return True when the transcript invoked the skill after its last compaction.
+def poteto_mode_status(all_transcript_lines: Iterable[str]) -> tuple[bool, bool]:
+    """Report whether the skill was invoked and whether it remains loaded.
 
     ::
 
-        Skill(poteto-mode) ... Read ... Edit               -> True
-        /poteto-mode typed as a command ... Read           -> True
-        Skill(poteto-mode) ... compact_boundary ... Read   -> False
-        Read ... Edit                                             -> False
+        Skill(poteto-mode) ... Read                   -> (True, True)
+        /poteto-mode ... compact_boundary             -> (True, False)
+        Skill(poteto-mode) ... compact_boundary ... Skill(poteto-mode)
+                                                      -> (True, True)
+        Read ... Edit                                 -> (False, False)
 
     Only lines naming the skill or a compaction are parsed, so a long transcript
     reads fast.
 
     Args:
         all_transcript_lines: The session transcript, one JSON entry per line.
+
+    Returns:
+        Whether the skill was invoked at any point and whether it is loaded now.
     """
+    was_invoked = False
     is_loaded = False
     for each_line in all_transcript_lines:
         all_entry_fields = _marker_entry(each_line)
         if all_entry_fields is not None:
             is_loaded = _is_loaded_after(all_entry_fields, is_loaded)
-    return is_loaded
+            was_invoked = was_invoked or is_loaded
+    return was_invoked, is_loaded
+
 
+def is_poteto_mode_loaded(all_transcript_lines: Iterable[str]) -> bool:
+    """Return whether the transcript invoked the skill after its last compaction.
+
+    Args:
+        all_transcript_lines: The session transcript, one JSON entry per line.
 
-def _is_loaded_in_transcript(transcript_path: object) -> bool:
+    Returns:
+        Whether the skill is loaded now.
+    """
+    return poteto_mode_status(all_transcript_lines)[1]
+
+
+def _status_in_transcript(transcript_path: object) -> tuple[bool, bool]:
     if not isinstance(transcript_path, str):
-        return False
+        return False, False
     try:
         with open(
             transcript_path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY
         ) as transcript:
-            return is_poteto_mode_loaded(transcript)
+            return poteto_mode_status(transcript)
     except OSError:
-        return False
+        return False, False
 
 
 def reminder_for(all_hook_fields: dict[str, object]) -> str | None:
-    """Return the reminder a session event carries, or None when the skill is in view.
+    """Return a reminder only for helpers or sessions that need the skill restored.
 
     ::
 
-        SessionStart, source compact                     -> COMPACTION_REMINDER
+        SessionStart, compact, skill invoked before      -> COMPACTION_REMINDER
+        SessionStart, compact, no prior invocation
+        or transcript unavailable                        -> None
         SubagentStart, workflow-subagent                 -> NOT_LOADED_REMINDER
-        UserPromptSubmit, transcript lacks the skill     -> NOT_LOADED_REMINDER
-        UserPromptSubmit, transcript loaded the skill    -> None
+        UserPromptSubmit, skill invoked then compacted   -> NOT_LOADED_REMINDER
+        UserPromptSubmit, skill loaded, never invoked,
+        or transcript unavailable                        -> None
 
     Args:
         all_hook_fields: The parsed hook input.
+
+    Returns:
+        The event's reminder, or None when no reminder is needed.
     """
     event_name = all_hook_fields.get("hook_event_name")
     if event_name == SESSION_START_EVENT_NAME:
-        return COMPACTION_REMINDER if all_hook_fields.get("source") == COMPACTION_SOURCE else None
+        if all_hook_fields.get("source") != COMPACTION_SOURCE:
+            return None
+        was_invoked, _ = _status_in_transcript(all_hook_fields.get("transcript_path"))
+        return COMPACTION_REMINDER if was_invoked else None
     if event_name == SUBAGENT_START_EVENT_NAME:
         is_workflow_helper = all_hook_fields.get("agent_type") == WORKFLOW_SUBAGENT_TYPE
         return NOT_LOADED_REMINDER if is_workflow_helper else None
     if event_name != USER_PROMPT_SUBMIT_EVENT_NAME:
         return None
-    if _is_loaded_in_transcript(all_hook_fields.get("transcript_path")):
-        return None
-    return NOT_LOADED_REMINDER
+    was_invoked, is_loaded = _status_in_transcript(all_hook_fields.get("transcript_path"))
+    return NOT_LOADED_REMINDER if was_invoked and not is_loaded else None
 
 
 def _is_subagent_spawn(all_hook_fields: dict[str, object]) -> bool:

package/hooks/session/test_skill_loaded_reminder.py

@@ -1,4 +1,4 @@
-"""Tests for skill_loaded_reminder. Checks every fresh context gets poteto-mode, and loaded ones hear nothing."""
+"""Tests for skill_loaded_reminder. Checks restoration after compaction and helper prompts."""
 
 import json
 import sys
@@ -167,14 +167,25 @@ class TestCodexSpawn:
 
     def test_a_codex_spawn_message_that_already_mentions_the_skill_is_left_alone(self) -> None:
         assert (
-            _run_main(
-                _agent_call({"message": "$poteto-mode\n\nFix it."}, tool_name="spawn_agent")
-            )
+            _run_main(_agent_call({"message": "$poteto-mode\n\nFix it."}, tool_name="spawn_agent"))
             == ""
         )
 
 
 class TestIsPotetoModeLoaded:
+    def test_status_without_a_skill_call_reports_no_invocation_or_load(self) -> None:
+        assert reminder.poteto_mode_status(iter([READ_CALL_LINE])) == (False, False)
+
+    def test_status_keeps_invocation_history_after_compaction(self) -> None:
+        assert reminder.poteto_mode_status(
+            iter([SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE, READ_CALL_LINE])
+        ) == (True, False)
+
+    def test_status_reports_the_skill_loaded_again_after_compaction(self) -> None:
+        assert reminder.poteto_mode_status(
+            iter([SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE, SKILL_CALL_LINE])
+        ) == (True, True)
+
     def test_a_skill_call_loads_it(self) -> None:
         assert reminder.is_poteto_mode_loaded([READ_CALL_LINE, SKILL_CALL_LINE, READ_CALL_LINE])
 
@@ -210,35 +221,106 @@ class TestIsPotetoModeLoaded:
 
 
 class TestReminderFor:
-    def test_a_user_turn_in_a_session_that_never_loaded_the_skill_gets_the_reminder(
+    def test_a_user_turn_in_a_session_that_never_loaded_the_skill_prints_nothing(
         self, tmp_path: Path
     ) -> None:
         transcript_path = _write_transcript(tmp_path, [READ_CALL_LINE])
+        assert _run_main(_user_turn(transcript_path)) == ""
+
+    def test_a_user_turn_after_the_skill_and_compaction_gets_the_reminder(
+        self, tmp_path: Path
+    ) -> None:
+        transcript_path = _write_transcript(
+            tmp_path, [SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE, READ_CALL_LINE]
+        )
         emitted = json.loads(_run_main(_user_turn(transcript_path)))
         hook_output = emitted["hookSpecificOutput"]
         assert hook_output["hookEventName"] == "UserPromptSubmit"
         assert hook_output["additionalContext"] == NOT_LOADED_REMINDER
         assert "poteto-mode" in NOT_LOADED_REMINDER
 
+    def test_a_user_turn_after_the_skill_is_reloaded_prints_nothing(self, tmp_path: Path) -> None:
+        transcript_path = _write_transcript(
+            tmp_path, [SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE, SKILL_CALL_LINE]
+        )
+        assert _run_main(_user_turn(transcript_path)) == ""
+
     def test_a_user_turn_in_a_session_that_loaded_the_skill_prints_nothing(
         self, tmp_path: Path
     ) -> None:
         transcript_path = _write_transcript(tmp_path, [SKILL_CALL_LINE, READ_CALL_LINE])
         assert _run_main(_user_turn(transcript_path)) == ""
 
-    def test_a_user_turn_with_no_transcript_yet_gets_the_reminder(self, tmp_path: Path) -> None:
-        assert (
-            reminder.reminder_for(_user_turn(tmp_path / "not-written-yet.jsonl"))
-            == NOT_LOADED_REMINDER
-        )
+    def test_a_user_turn_with_no_transcript_yet_prints_nothing(self, tmp_path: Path) -> None:
+        assert _run_main(_user_turn(tmp_path / "not-written-yet.jsonl")) == ""
 
-    def test_session_start_after_compaction_tells_the_session_to_invoke_it_again(self) -> None:
-        emitted = json.loads(_run_main({"hook_event_name": "SessionStart", "source": "compact"}))
+    def test_session_start_after_compaction_tells_a_prior_user_to_invoke_it_again(
+        self, tmp_path: Path
+    ) -> None:
+        transcript_path = _write_transcript(tmp_path, [SKILL_CALL_LINE, READ_CALL_LINE])
+        emitted = json.loads(
+            _run_main(
+                {
+                    "hook_event_name": "SessionStart",
+                    "source": "compact",
+                    "transcript_path": str(transcript_path),
+                }
+            )
+        )
         hook_output = emitted["hookSpecificOutput"]
         assert hook_output["hookEventName"] == "SessionStart"
         assert hook_output["additionalContext"] == COMPACTION_REMINDER
         assert "poteto-mode" in COMPACTION_REMINDER
 
+    def test_session_start_after_a_written_boundary_reminds_a_prior_user(
+        self, tmp_path: Path
+    ) -> None:
+        transcript_path = _write_transcript(tmp_path, [SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE])
+        assert (
+            reminder.reminder_for(
+                {
+                    "hook_event_name": "SessionStart",
+                    "source": "compact",
+                    "transcript_path": str(transcript_path),
+                }
+            )
+            == COMPACTION_REMINDER
+        )
+
+    def test_session_start_after_compaction_without_a_prior_skill_call_prints_nothing(
+        self, tmp_path: Path
+    ) -> None:
+        transcript_path = _write_transcript(tmp_path, [READ_CALL_LINE])
+        assert (
+            _run_main(
+                {
+                    "hook_event_name": "SessionStart",
+                    "source": "compact",
+                    "transcript_path": str(transcript_path),
+                }
+            )
+            == ""
+        )
+
+    def test_session_start_after_compaction_without_a_transcript_path_prints_nothing(
+        self,
+    ) -> None:
+        assert _run_main({"hook_event_name": "SessionStart", "source": "compact"}) == ""
+
+    def test_session_start_after_compaction_with_an_unreadable_transcript_prints_nothing(
+        self, tmp_path: Path
+    ) -> None:
+        assert (
+            _run_main(
+                {
+                    "hook_event_name": "SessionStart",
+                    "source": "compact",
+                    "transcript_path": str(tmp_path / "not-written-yet.jsonl"),
+                }
+            )
+            == ""
+        )
+
     def test_a_resumed_session_keeps_its_context_and_prints_nothing(self) -> None:
         assert _run_main({"hook_event_name": "SessionStart", "source": "resume"}) == ""
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.38.2",
+    "version": "8.39.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {