claude-dev-env 1.40.0 → 1.41.0

package/hooks/lifecycle/pr_converge_bugteam_skill_tracker.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: record formal bugteam Skill invocations into pr-converge state.
+
+Companion to ``pr_converge_bugteam_enforcer``. On every
+``Skill({skill: "bugteam"})`` invocation, this hook stamps
+``$CLAUDE_JOB_DIR/pr-converge-state.json`` with
+``bugteam_skill_invoked_at_head = current_head`` and
+``bugteam_skill_invoked_at_tick = tick_count`` so the enforcer can confirm
+the formal Skill fired this tick at the current HEAD before allowing any
+follow-on clean-coder audit-shaped Agent spawn.
+
+``qbug`` invocations are deliberately ignored — qbug is not an accepted
+substitute for the formal bugteam Skill at Step 5.
+
+The hook never blocks: it returns exit 0 in every branch so the Skill call
+proceeds unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import TextIO
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.pr_converge_bugteam_enforcer_constants import (
+    BUGTEAM_SKILL_NAME,
+    SKILL_TOOL_NAME,
+    STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_HEAD,
+    STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_TICK,
+    STATE_FIELD_CURRENT_HEAD,
+    STATE_FIELD_TICK_COUNT,
+    STATE_FILE_ATOMIC_WRITE_SUFFIX,
+    STATE_FILE_JSON_INDENT_SPACES,
+)
+from config.pr_converge_bugteam_enforcer_state import (
+    load_state_dictionary,
+    resolve_state_path,
+)
+
+
+def _atomic_write_state(state_path: Path, state_by_field: dict[str, object]) -> None:
+    """Serialize state to disk atomically via tempfile + rename.
+
+    Args:
+        state_path: Destination ``pr-converge-state.json`` path.
+        state_by_field: Updated state mapping each field name to its value.
+    """
+    parent_directory = state_path.parent
+    parent_directory.mkdir(parents=True, exist_ok=True)
+    encoded_text = json.dumps(state_by_field, indent=STATE_FILE_JSON_INDENT_SPACES, sort_keys=True)
+    with tempfile.NamedTemporaryFile(
+        mode="w",
+        encoding="utf-8",
+        dir=str(parent_directory),
+        delete=False,
+        suffix=STATE_FILE_ATOMIC_WRITE_SUFFIX,
+    ) as temporary_handle:
+        temporary_handle.write(encoded_text)
+        temporary_path = Path(temporary_handle.name)
+    try:
+        os.replace(str(temporary_path), str(state_path))
+    except OSError:
+        Path(temporary_path).unlink(missing_ok=True)
+        raise
+
+
+def _emit_missing_state_warning(output_stream: TextIO) -> None:
+    """Write the missing-state warning to the provided stream.
+
+    Args:
+        output_stream: Writable text stream — production code passes
+            ``sys.stderr``; tests pass a ``StringIO`` to capture the message.
+    """
+    output_stream.write(
+        "pr_converge_bugteam_skill_tracker: state file lacks current_head or "
+        "tick_count; bugteam invocation NOT recorded\n"
+    )
+    output_stream.flush()
+
+
+def _record_bugteam_skill_invocation(
+    state_by_field: dict[str, object],
+) -> dict[str, object] | None:
+    """Return a copy of state with bugteam-Skill invocation fields stamped, or None on no-op.
+
+    The two stamp fields are owned exclusively by this tracker. Concurrent
+    writes from the orchestrator never touch them, so the read-modify-write
+    window cannot lose an orchestrator update on these specific keys.
+
+    When ``current_head`` (str) or ``tick_count`` (int) is missing or wrong-typed,
+    the function emits a stderr warning via ``_emit_missing_state_warning`` and
+    returns ``None`` so the caller skips the disk write entirely. Skipping the
+    no-op write narrows the read-modify-write window against the orchestrator —
+    concurrent updates to non-stamp fields (``phase``, ``tick_count``, etc.)
+    cannot be silently lost by a tracker rewrite that changes nothing.
+
+    Args:
+        state_by_field: Existing pr-converge state mapping each field name to
+            its value.
+
+    Returns:
+        New dictionary identical to ``state_by_field`` plus
+        ``bugteam_skill_invoked_at_head`` set to ``current_head`` and
+        ``bugteam_skill_invoked_at_tick`` set to ``tick_count`` when both
+        source fields are present and well-typed; ``None`` when either source
+        field is missing or wrong-typed, signaling the caller to skip the
+        atomic write.
+    """
+    current_head = state_by_field.get(STATE_FIELD_CURRENT_HEAD)
+    current_tick = state_by_field.get(STATE_FIELD_TICK_COUNT)
+    if not isinstance(current_head, str) or not isinstance(current_tick, int):
+        _emit_missing_state_warning(sys.stderr)
+        return None
+    updated_state: dict[str, object] = dict(state_by_field)
+    updated_state[STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_HEAD] = current_head
+    updated_state[STATE_FIELD_BUGTEAM_SKILL_INVOKED_AT_TICK] = current_tick
+    return updated_state
+
+
+def _is_formal_bugteam_skill_invocation(payload_by_field: dict[str, object]) -> bool:
+    """Return True when this hook invocation matches the formal bugteam Skill.
+
+    Args:
+        payload_by_field: The full PreToolUse hook payload (already JSON-parsed),
+            keyed by top-level field name.
+
+    Returns:
+        True when ``tool_name == "Skill"`` and ``tool_input["skill"]
+        == "bugteam"``. Returns False for qbug and every other skill.
+    """
+    if payload_by_field.get("tool_name", "") != SKILL_TOOL_NAME:
+        return False
+    tool_input = payload_by_field.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return False
+    return tool_input.get("skill", "") == BUGTEAM_SKILL_NAME
+
+
+def _emit_state_write_error(state_write_error: OSError, output_stream: TextIO) -> None:
+    """Write the state-write failure message to the provided stream.
+
+    Args:
+        state_write_error: The OSError raised by ``_atomic_write_state``.
+        output_stream: Writable text stream — production code passes
+            ``sys.stderr``; tests pass a ``StringIO`` to capture the message.
+    """
+    output_stream.write(
+        f"pr_converge_bugteam_skill_tracker: state write failed; "
+        f"stamp not recorded: {state_write_error}\n"
+    )
+    output_stream.flush()
+
+
+def main() -> None:
+    """Tracker entry point for the PreToolUse:Skill hook.
+
+    Reads the PreToolUse payload from stdin, records a formal
+    ``Skill({skill: "bugteam"})`` invocation in the pr-converge state file,
+    and always returns 0 — including on a state-write failure, since a
+    non-zero PreToolUse exit would block the very Skill invocation this
+    hook exists to record. State-write failures are surfaced via
+    ``_emit_state_write_error`` to stderr so the operator still sees the
+    protocol-corruption signal.
+    """
+    try:
+        hook_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(hook_payload, dict):
+        return
+    if not _is_formal_bugteam_skill_invocation(hook_payload):
+        return
+    state_path = resolve_state_path()
+    if state_path is None:
+        return
+    parsed_state = load_state_dictionary(state_path)
+    if parsed_state is None:
+        return
+    updated_state = _record_bugteam_skill_invocation(parsed_state)
+    if updated_state is None:
+        return
+    try:
+        _atomic_write_state(state_path, updated_state)
+    except OSError as state_write_error:
+        _emit_state_write_error(state_write_error, sys.stderr)
+        return
+    return
+
+
+if __name__ == "__main__":
+    main()

package/hooks/lifecycle/test_pr_converge_bugteam_skill_tracker.py

@@ -0,0 +1,283 @@
+"""Unit tests for the pr_converge_bugteam_skill_tracker PreToolUse hook.
+
+Covers the bugteam-only update path: only Skill({skill: "bugteam"}) updates
+the invocation fields in $CLAUDE_JOB_DIR/pr-converge-state.json (the file
+named by PR_CONVERGE_STATE_FILENAME). qbug, other skills, and missing-state
+cases all return exit 0 without modifying state.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+from typing import Any
+from unittest import mock
+
+import pytest
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "pr_converge_bugteam_skill_tracker",
+    _HOOK_DIR / "pr_converge_bugteam_skill_tracker.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+from config.pr_converge_bugteam_enforcer_constants import (
+    CLAUDE_JOB_DIR_ENV_VAR,
+    PR_CONVERGE_STATE_FILENAME,
+)
+
+_HEAD_SHA = "abc123def456abc123def456abc123def456abcd"
+_TICK_COUNT = 4
+
+
+def _write_state(state_directory: pathlib.Path, state: dict[str, Any]) -> pathlib.Path:
+    state_path = state_directory / PR_CONVERGE_STATE_FILENAME
+    state_path.write_text(json.dumps(state), encoding="utf-8")
+    return state_path
+
+
+def _baseline_state() -> dict[str, Any]:
+    return {
+        "phase": "BUGTEAM",
+        "current_head": _HEAD_SHA,
+        "tick_count": _TICK_COUNT,
+        "bugteam_skill_invoked_at_head": None,
+        "bugteam_skill_invoked_at_tick": None,
+    }
+
+
+def _read_state(state_directory: pathlib.Path) -> dict[str, Any]:
+    state_path = state_directory / PR_CONVERGE_STATE_FILENAME
+    return json.loads(state_path.read_text(encoding="utf-8"))
+
+
+def _run_main_with_io(input_text: str) -> None:
+    with mock.patch("sys.stdin", io.StringIO(input_text)):
+        with mock.patch("sys.stdout", new_callable=io.StringIO):
+            try:
+                hook_module.main()
+            except SystemExit:
+                pass
+
+
+def _run_main_capturing_stderr(input_text: str) -> str:
+    with mock.patch("sys.stdin", io.StringIO(input_text)):
+        with mock.patch("sys.stdout", new_callable=io.StringIO):
+            with mock.patch("sys.stderr", new_callable=io.StringIO) as captured_stderr:
+                try:
+                    hook_module.main()
+                except SystemExit:
+                    pass
+                return captured_stderr.getvalue()
+
+
+@pytest.fixture()
+def claude_job_directory(tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch) -> pathlib.Path:
+    monkeypatch.setenv(CLAUDE_JOB_DIR_ENV_VAR, str(tmp_path))
+    return tmp_path
+
+
+def test_should_record_invocation_when_bugteam_skill_fires(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(claude_job_directory, _baseline_state())
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam", "args": "https://github.com/o/r/pull/1"},
+    }
+    _run_main_with_io(json.dumps(skill_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert updated_state["bugteam_skill_invoked_at_head"] == _HEAD_SHA
+    assert updated_state["bugteam_skill_invoked_at_tick"] == _TICK_COUNT
+
+
+def test_should_not_record_invocation_when_qbug_skill_fires(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(claude_job_directory, _baseline_state())
+    qbug_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "qbug"},
+    }
+    _run_main_with_io(json.dumps(qbug_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert updated_state["bugteam_skill_invoked_at_head"] is None
+    assert updated_state["bugteam_skill_invoked_at_tick"] is None
+
+
+def test_should_ignore_unrelated_skills(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(claude_job_directory, _baseline_state())
+    other_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "agent-prompt"},
+    }
+    _run_main_with_io(json.dumps(other_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert updated_state["bugteam_skill_invoked_at_head"] is None
+
+
+def test_should_ignore_non_skill_tools(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    _write_state(claude_job_directory, _baseline_state())
+    agent_payload: dict[str, Any] = {
+        "tool_name": "Agent",
+        "tool_input": {"subagent_type": "clean-coder", "prompt": "fix this"},
+    }
+    _run_main_with_io(json.dumps(agent_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert updated_state["bugteam_skill_invoked_at_head"] is None
+
+
+def test_should_no_op_when_state_file_absent(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    _run_main_with_io(json.dumps(skill_payload))
+    assert not (claude_job_directory / PR_CONVERGE_STATE_FILENAME).exists()
+
+
+def test_should_no_op_when_state_json_is_malformed(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    state_path = claude_job_directory / PR_CONVERGE_STATE_FILENAME
+    state_path.write_text("{not valid json", encoding="utf-8")
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    _run_main_with_io(json.dumps(skill_payload))
+    assert state_path.read_text(encoding="utf-8") == "{not valid json"
+
+
+def test_should_preserve_other_state_fields_on_update(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    baseline_state = _baseline_state()
+    baseline_state["bugbot_clean_at"] = _HEAD_SHA
+    baseline_state["copilot_wait_count"] = 2
+    _write_state(claude_job_directory, baseline_state)
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    _run_main_with_io(json.dumps(skill_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert updated_state["bugbot_clean_at"] == _HEAD_SHA
+    assert updated_state["copilot_wait_count"] == 2
+    assert updated_state["bugteam_skill_invoked_at_head"] == _HEAD_SHA
+
+
+def test_should_no_op_when_claude_job_dir_env_var_absent(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv(CLAUDE_JOB_DIR_ENV_VAR, raising=False)
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    _run_main_with_io(json.dumps(skill_payload))
+
+
+def test_should_no_op_when_payload_is_malformed_json(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    baseline_state = _baseline_state()
+    _write_state(claude_job_directory, baseline_state)
+    _run_main_with_io("not valid json {{{")
+    updated_state = _read_state(claude_job_directory)
+    assert updated_state["bugteam_skill_invoked_at_head"] is None
+
+
+def test_should_leave_state_unchanged_when_current_head_is_missing(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    state_without_head = _baseline_state()
+    del state_without_head["current_head"]
+    _write_state(claude_job_directory, state_without_head)
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    captured_stderr = _run_main_capturing_stderr(json.dumps(skill_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert "current_head" not in updated_state
+    assert updated_state.get("bugteam_skill_invoked_at_head") is None
+    assert updated_state.get("bugteam_skill_invoked_at_tick") is None
+    assert "current_head or tick_count" in captured_stderr
+
+
+def test_should_leave_state_unchanged_when_tick_count_is_missing(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    state_without_tick = _baseline_state()
+    del state_without_tick["tick_count"]
+    _write_state(claude_job_directory, state_without_tick)
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    captured_stderr = _run_main_capturing_stderr(json.dumps(skill_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert "tick_count" not in updated_state
+    assert updated_state.get("bugteam_skill_invoked_at_head") is None
+    assert updated_state.get("bugteam_skill_invoked_at_tick") is None
+    assert "current_head or tick_count" in captured_stderr
+
+
+def test_should_preserve_prior_stamp_when_current_head_becomes_missing(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    prior_head = "feedface0000feedface0000feedface0000feed"
+    prior_tick = 3
+    state_with_prior_stamp = _baseline_state()
+    state_with_prior_stamp["bugteam_skill_invoked_at_head"] = prior_head
+    state_with_prior_stamp["bugteam_skill_invoked_at_tick"] = prior_tick
+    del state_with_prior_stamp["current_head"]
+    _write_state(claude_job_directory, state_with_prior_stamp)
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    _run_main_capturing_stderr(json.dumps(skill_payload))
+    updated_state = _read_state(claude_job_directory)
+    assert updated_state["bugteam_skill_invoked_at_head"] == prior_head
+    assert updated_state["bugteam_skill_invoked_at_tick"] == prior_tick
+
+
+def test_should_skip_atomic_write_when_state_missing_required_fields(
+    claude_job_directory: pathlib.Path,
+) -> None:
+    state_without_head = _baseline_state()
+    del state_without_head["current_head"]
+    _write_state(claude_job_directory, state_without_head)
+    skill_payload: dict[str, Any] = {
+        "tool_name": "Skill",
+        "tool_input": {"skill": "bugteam"},
+    }
+    with mock.patch.object(hook_module, "_atomic_write_state") as patched_atomic_write:
+        with mock.patch("sys.stdin", io.StringIO(json.dumps(skill_payload))):
+            with mock.patch("sys.stdout", new_callable=io.StringIO):
+                with mock.patch("sys.stderr", new_callable=io.StringIO):
+                    try:
+                        hook_module.main()
+                    except SystemExit:
+                        pass
+        assert patched_atomic_write.call_count == 0

package/hooks/session/gh_pr_author_session_cleanup.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""SessionStart hook — sweep stale gh-pr-author swap state files at session start.
+
+The PreToolUse enforcer (``gh_pr_author_enforcer.py``) writes a per-session
+state file recording the original gh CLI account before swapping to
+``GITHUB_DEFAULT_ACCOUNT``. The PostToolUse companion
+(``gh_pr_author_restore.py``) reads that file and switches back when
+``gh pr create`` finishes. When a session is interrupted between the
+swap and the restore — a crash, a downstream PreToolUse deny that fires
+*after* the enforcer's swap completed, or any other path that skips
+PostToolUse — the user is left on ``GITHUB_DEFAULT_ACCOUNT`` with a
+stale state file on disk.
+
+This hook runs at the start of every Claude Code session. When
+``GITHUB_DEFAULT_ACCOUNT`` is set, it scans ``tempfile.gettempdir()``
+for every file matching ``{STATE_FILE_PREFIX}*{STATE_FILE_SUFFIX}``,
+reads the original account from each, runs ``gh auth switch --user
+<original>``, and deletes the file. A state file whose switch fails is
+left in place so the next session can retry. The hook is a strict no-op
+when ``GITHUB_DEFAULT_ACCOUNT`` is unset, so users who have not opted
+into the swap workflow are completely unaffected.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+_hooks_tree_path = str(Path(__file__).absolute().parent.parent)
+if _hooks_tree_path not in sys.path:
+    sys.path.insert(0, _hooks_tree_path)
+
+from _gh_pr_author_swap_utils import (  # noqa: E402  # sys.path shim above must run first
+    _delete_state_file,
+    _lstat_indicates_attacker_planted,
+    _read_original_account,
+    _switch_gh_account,
+    _write_line,
+)
+from config.gh_pr_author_swap_constants import (  # noqa: E402  # sys.path shim above must run first
+    REQUIRED_ACCOUNT_ENV_VAR,
+    STATE_FILE_PREFIX,
+    STATE_FILE_STALE_AGE_SECONDS,
+    STATE_FILE_SUFFIX,
+)
+
+
+def _collect_stale_state_files(temp_directory: Path) -> list[Path]:
+    """Return swap-state files older than the stale threshold and safe to process.
+
+    A state file younger than ``STATE_FILE_STALE_AGE_SECONDS`` is
+    treated as belonging to a concurrent Claude Code session that may
+    still be mid-``gh pr create``. Sweeping such a file would steal the
+    active session's restore target. Files older than the threshold are
+    overwhelmingly likely to be stale — the enforcer-to-restore window
+    is bounded by the gh subprocess timeouts (10s switch + 5s api user
+    + filesystem work), so any file older than
+    ``STATE_FILE_STALE_AGE_SECONDS`` is past the longest plausible
+    active window.
+
+    Each candidate is also screened for ownership and permission bits
+    matching the enforcer's write contract. A file with mode bits other
+    than ``STATE_FILE_PERMISSION_MODE`` or (on POSIX) owned by a
+    different user is silently skipped — it was not written by an
+    enforcer running as the current user and must not be allowed to
+    drive ``gh auth switch``.
+
+    The candidate is inspected via ``lstat`` rather than ``stat`` so a
+    symlink at the predictable swap-state path is screened on its own
+    metadata, not on whatever the symlink resolves to. Any entry that
+    is not a regular file (symlink, socket, fifo, device) is silently
+    skipped. The enforcer creates state files with ``O_NOFOLLOW``;
+    mirroring that contract here closes the symlink-hijack window where
+    an attacker plants a symlink pointing to a legitimate 0o600 file
+    owned by the current user to trick the cleanup hook into reading
+    that file as a swap-state payload.
+
+    Returned paths are sorted by modification time in ascending order so
+    that when the caller iterates and runs ``gh auth switch`` for each
+    file, the newest stale file is processed LAST. ``gh auth switch``
+    is global state — only the last switch wins — so processing the
+    newest file last leaves the gh CLI on the most recently captured
+    original account when multiple sessions crashed with different
+    original accounts. The single ``lstat`` syscall performed per
+    candidate is reused for both the attacker-planted screen and the
+    mtime ordering key so the sort does not double-stat.
+
+    Args:
+        temp_directory: System temp directory returned by
+            ``tempfile.gettempdir()``.
+
+    Returns:
+        List of swap-state file paths that are regular files whose
+        modification time is older than ``STATE_FILE_STALE_AGE_SECONDS``
+        seconds before now and whose ownership/mode bits match the
+        enforcer's write contract. Sorted by mtime ascending so the
+        newest stale file is last in iteration order. Empty list when
+        the temp directory cannot be listed.
+    """
+    glob_pattern = f"{STATE_FILE_PREFIX}*{STATE_FILE_SUFFIX}"
+    current_time_seconds = time.time()
+    all_stale_candidates_with_mtime: list[tuple[float, Path]] = []
+    try:
+        all_candidate_paths = list(temp_directory.glob(glob_pattern))
+    except OSError:
+        return []
+    for each_candidate_path in all_candidate_paths:
+        try:
+            file_lstat_result = each_candidate_path.lstat()
+        except OSError:
+            continue
+        if _lstat_indicates_attacker_planted(file_lstat_result):
+            continue
+        file_age_seconds = current_time_seconds - file_lstat_result.st_mtime
+        if file_age_seconds >= STATE_FILE_STALE_AGE_SECONDS:
+            all_stale_candidates_with_mtime.append(
+                (file_lstat_result.st_mtime, each_candidate_path)
+            )
+    all_stale_candidates_with_mtime.sort(key=lambda each_mtime_path_pair: each_mtime_path_pair[0])
+    return [each_mtime_path_pair[1] for each_mtime_path_pair in all_stale_candidates_with_mtime]
+
+
+def _restore_stale_state_file(state_file: Path) -> None:
+    """Restore one stale state file: switch back, then delete on success.
+
+    A malformed state file is deleted without a switch attempt. A
+    well-formed file whose switch attempt fails is left on disk so the
+    next session-start can retry.
+
+    Args:
+        state_file: Absolute path to a candidate state file.
+    """
+    original_account = _read_original_account(state_file)
+    if original_account is None:
+        _delete_state_file(state_file)
+        return
+    has_switched_account = _switch_gh_account(original_account)
+    if has_switched_account:
+        _delete_state_file(state_file)
+    else:
+        _write_line(
+            f"[gh-pr-author-cleanup] failed to restore active gh account to {original_account!r} from "
+            f"stale state file {state_file}; left in place for next session",
+            sys.stderr,
+        )
+
+
+def main() -> None:
+    """Sweep stale gh-pr-author swap state files when the workflow is enabled.
+
+    Exits 0 in every path. When ``GITHUB_DEFAULT_ACCOUNT`` is unset the
+    hook returns immediately so users who have not opted into the swap
+    workflow see no behavior change. Otherwise iterates every matching
+    state file under ``tempfile.gettempdir()`` and restores each one
+    independently — a failure on one file does not block the others.
+    """
+    required_account = os.environ.get(REQUIRED_ACCOUNT_ENV_VAR, "").strip()
+    if not required_account:
+        return
+    temp_directory = Path(tempfile.gettempdir())
+    all_stale_state_files = _collect_stale_state_files(temp_directory)
+    for each_state_file in all_stale_state_files:
+        _restore_stale_state_file(each_state_file)
+
+
+if __name__ == "__main__":
+    main()