Add the Witch role (#10)

The Witch is a villager with two one-time potions. Each night she learns who
the werewolves attacked and may use a healing potion to save them and/or a
poison potion to kill any one player.

- roles.py: new Role.WITCH; standard_setup seats one once the village has five
  or more seats.
- engine.py: _witch_action runs the Witch's turn after the doctor; the night
  phase is reworked to resolve multiple simultaneous deaths (_announce_deaths),
  each of which can still trigger a Hunter shot. Potion use is tracked on
  GameState so each potion is strictly once-per-game.
- agents: new concrete Agent.witch_turn; RandomAgent and LLMAgent override it,
  CLI HumanAgent prompts for it. The offline mock banks both potions.
- prompts: a dedicated witch_request template.
- 3 new tests covering the heal and poison potions.

Closes #2

Co-authored-by: JuneQQQ <june1243134432@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -15,9 +15,14 @@ All notable changes to this project are documented here. The format follows
   — the `deepwolf.game.transcript` module and a `--transcript PATH` flag on
   `deepwolf simulate` write a finished game as a versioned, machine-readable
   JSON record (players, full event log, winner).
+- **Witch role** ([#2](https://github.com/JuneQQQ/deepwolf/issues/2)) — a
+  villager with two one-time potions. Each night the Witch learns who the
+  werewolves attacked and may spend a healing potion to save them and/or a
+  poison potion to kill any player. The night phase now resolves multiple
+  simultaneous deaths.
 
 ### Planned
-- Additional roles: Witch, Cupid.
+- Additional roles: Cupid.
 - A model leaderboard built from arena runs.
 
 ## [0.1.0] — 2026-05-18

README.md

@@ -32,7 +32,7 @@ to a human as a copilot.
 ## Features
 
 - ♟️ **A strict, seeded rules engine.** Night/day cycle with Werewolf, Seer,
-  Doctor and Hunter abilities. Every game is reproducible from a seed; an
+  Doctor, Hunter and Witch abilities. Every game is reproducible from a seed; an
   illegal or hallucinated agent move can never corrupt a game.
 - 🔌 **Vendor-neutral LLMs.** Any OpenAI-compatible endpoint — OpenAI,
   DeepSeek, Xiaomi MiMo, Groq, OpenRouter, a local server. Change one env var.
@@ -151,7 +151,7 @@ a natural-language read of the *statements* the heuristic ignores.
 ## Roadmap
 
 See [CHANGELOG.md](CHANGELOG.md) and the [issue tracker](https://github.com/JuneQQQ/deepwolf/issues).
-Near-term: more roles (Witch, Cupid) and a leaderboard of models in the arena.
+Near-term: more roles (Cupid) and a leaderboard of models in the arena.
 
 ## Contributing
 

deepwolf/agents/base.py

@@ -48,3 +48,19 @@ def dying_shot(self, view: PlayerView) -> int:
         """
         pool = view.others_alive() or list(view.living_ids)
         return view.rng.choice(pool)
+
+    def witch_turn(
+        self,
+        view: PlayerView,
+        victim: int | None,
+        can_heal: bool,
+        can_poison: bool,
+    ) -> tuple[bool, int | None]:
+        """Return ``(use_heal, poison_target)`` for the Witch's night.
+
+        ``victim`` is who the werewolves attacked (``None`` if they did not, or
+        the Witch cannot know). ``can_heal`` / ``can_poison`` say which one-time
+        potions are still available. Only called for a living Witch. Concrete,
+        so existing agents need no change; the default uses no potions.
+        """
+        return (False, None)

deepwolf/agents/llm_agent.py

@@ -60,6 +60,21 @@ def dying_shot(self, view: PlayerView) -> int:
         candidates = view.others_alive() or list(view.living_ids)
         return self._decide(view, T.KIND_SHOOT, candidates)
 
+    def witch_turn(
+        self, view: PlayerView, victim: int | None, can_heal: bool, can_poison: bool
+    ) -> tuple[bool, int | None]:
+        messages = [
+            {"role": "system", "content": T.system_message(view)},
+            {"role": "user", "content": T.witch_request(view, victim, can_heal, can_poison)},
+        ]
+        data = _parse_json(self._call(messages))
+        if not data:
+            return (False, None)
+        heal = bool(data.get("heal")) and can_heal
+        poison = data.get("poison")
+        poison_target = poison if (isinstance(poison, int) and can_poison) else None
+        return (heal, poison_target)
+
     # ------------------------------------------------------------- internals
     def _decide(self, view: PlayerView, kind: str, candidates: list[int]) -> int:
         messages = self._messages(view, kind, candidates)

deepwolf/agents/random_agent.py

@@ -33,6 +33,15 @@ def vote(self, view: PlayerView) -> int:
     def speak(self, view: PlayerView) -> str:
         return view.rng.choice(_FILLER)
 
+    def witch_turn(
+        self, view: PlayerView, victim: int | None, can_heal: bool, can_poison: bool
+    ) -> tuple[bool, int | None]:
+        heal = can_heal and view.rng.random() < 0.5
+        poison: int | None = None
+        if can_poison and view.rng.random() < 0.3 and view.others_alive():
+            poison = view.rng.choice(view.others_alive())
+        return (heal, poison)
+
     @staticmethod
     def _pool(view: PlayerView) -> list[int]:
         return view.others_alive() or list(view.living_ids)

deepwolf/cli.py

@@ -123,6 +123,28 @@ def dying_shot(self, view: PlayerView) -> int:
         pool = view.others_alive() or list(view.living_ids)
         return self._ask(view, pool, "You are the dying Hunter — who do you shoot?")
 
+    def witch_turn(
+        self, view: PlayerView, victim: int | None, can_heal: bool, can_poison: bool
+    ) -> tuple[bool, int | None]:
+        self._banner(view, "WITCH")
+        if victim is not None:
+            self.console.print(f"  The werewolves attacked {view.name(victim)} (P{victim}).")
+        else:
+            self.console.print("  You sense no werewolf attack you could counter.")
+        heal = False
+        if can_heal and victim is not None:
+            answer = self.console.input(f"  Use your HEALING potion on P{victim}? [y/N] ")
+            heal = answer.strip().lower().startswith("y")
+        poison: int | None = None
+        if can_poison:
+            answer = self.console.input(
+                "  POISON potion — enter a player id to kill, or blank to skip: "
+            )
+            raw = answer.strip().lstrip("Pp")
+            if raw.isdigit() and int(raw) in view.others_alive():
+                poison = int(raw)
+        return (heal, poison)
+
     def _banner(self, view: PlayerView, phase: str) -> None:
         self.console.rule(f"You are {view.me_name} (P{view.me_id}) — {view.me_role.value} — {phase}")
         for note in view.private_notes:

deepwolf/game/engine.py

@@ -109,24 +109,40 @@ def _night_phase(self) -> None:
         victim = self._werewolf_target()
         self._seer_inspection()
         protected = self._doctor_protection()
+        healed, poisoned = self._witch_action(victim)
 
-        if victim is not None and victim != protected:
-            self._kill(victim, "killed by werewolves")
-            reveal = self._role_reveal(victim)
-            self._emit(Event(
-                EventType.DEATH_ANNOUNCED, s.day, "night",
-                f"At dawn the village finds {s.name(victim)} (P{victim}) dead."
-                + reveal[0],
-                target=victim, data=reveal[1],
-            ))
-            self._process_hunter(victim)
-        else:
-            saved = protected is not None and protected == victim
+        # Collect the night's deaths, then announce them together.
+        deaths: list[tuple[int, str]] = []
+        if victim is not None and victim != protected and not healed:
+            deaths.append((victim, "killed by werewolves"))
+        if poisoned is not None and poisoned not in {d[0] for d in deaths}:
+            deaths.append((poisoned, "poisoned by the Witch"))
+
+        if not deaths:
+            saved = victim is not None and (victim == protected or healed)
             self._emit(Event(
                 EventType.QUIET_NIGHT, s.day, "night",
                 "The village wakes to find everyone alive."
-                + (" The doctor's vigil paid off." if saved else ""),
+                + (" Someone was watched over in the dark." if saved else ""),
+            ))
+            return
+        self._announce_deaths(deaths)
+
+    def _announce_deaths(self, deaths: list[tuple[int, str]]) -> None:
+        """Mark each night death, announce it, and fire any Hunter shots."""
+        s = self.state
+        for pid, cause in deaths:
+            if not s.player(pid).alive:
+                continue  # already taken by an earlier death this night
+            self._kill(pid, cause)
+            reveal = self._role_reveal(pid)
+            self._emit(Event(
+                EventType.DEATH_ANNOUNCED, s.day, "night",
+                f"At dawn the village finds {s.name(pid)} (P{pid}) dead."
+                + reveal[0],
+                target=pid, data=reveal[1],
             ))
+            self._process_hunter(pid)
 
     def _werewolf_target(self) -> int | None:
         s = self.state
@@ -178,6 +194,59 @@ def _doctor_protection(self) -> int | None:
         ))
         return target
 
+    def _witch_action(self, victim: int | None) -> tuple[bool, int | None]:
+        """Run the Witch's night, returning (victim healed?, poison target)."""
+        s = self.state
+        witches = s.living_with_role(Role.WITCH)
+        if not witches:
+            return False, None
+        witch = witches[0]
+        can_heal = not s.witch_heal_used and victim is not None
+        can_poison = not s.witch_poison_used
+        if not (can_heal or can_poison):
+            return False, None
+
+        if victim is not None:
+            self._emit(Event(
+                EventType.WITCH_NIGHT_INFO, s.day, "night",
+                f"The werewolves attacked {s.name(victim)} (P{victim}) tonight.",
+                target=victim, public=False, visible_to=frozenset({witch.id}),
+            ))
+        view = build_view(s, witch.id, Phase.NIGHT)
+        try:
+            heal, poison = self.agents[witch.id].witch_turn(
+                view, victim, can_heal, can_poison
+            )
+        except Exception:  # noqa: BLE001 - an agent error must not crash a game
+            heal, poison = False, None
+
+        healed = False
+        if heal and can_heal and victim is not None:
+            s.witch_heal_used = True
+            healed = True
+            self._emit(Event(
+                EventType.WITCH_POTION, s.day, "night",
+                f"You use your healing potion on {s.name(victim)} (P{victim}).",
+                target=victim, public=False, visible_to=frozenset({witch.id}),
+                data={"potion": "heal"},
+            ))
+        poison_target: int | None = None
+        if (
+            can_poison
+            and isinstance(poison, int)
+            and poison in s.living_ids()
+            and poison != witch.id
+        ):
+            s.witch_poison_used = True
+            poison_target = poison
+            self._emit(Event(
+                EventType.WITCH_POTION, s.day, "night",
+                f"You use your poison potion on {s.name(poison)} (P{poison}).",
+                target=poison, public=False, visible_to=frozenset({witch.id}),
+                data={"potion": "poison"},
+            ))
+        return healed, poison_target
+
     # ----------------------------------------------------------------- day
     def _day_phase(self) -> None:
         s = self.state

deepwolf/game/events.py

@@ -20,6 +20,8 @@ class EventType(str, Enum):
     WEREWOLF_TARGET = "werewolf_target"  # private: a wolf names a victim
     SEER_RESULT = "seer_result"        # private: the seer's inspection
     DOCTOR_PROTECT = "doctor_protect"  # private: the doctor's choice
+    WITCH_NIGHT_INFO = "witch_night_info"  # private: who the wolves attacked
+    WITCH_POTION = "witch_potion"      # private: a potion the witch used
     DAY_BREAKS = "day_breaks"          # public
     DEATH_ANNOUNCED = "death_announced"  # public
     QUIET_NIGHT = "quiet_night"        # public: nobody died

deepwolf/game/roles.py

@@ -29,6 +29,7 @@ class Role(str, Enum):
     SEER = "seer"
     DOCTOR = "doctor"
     HUNTER = "hunter"
+    WITCH = "witch"
 
     @property
     def faction(self) -> Faction:
@@ -37,7 +38,7 @@ def faction(self) -> Faction:
     @property
     def has_night_action(self) -> bool:
         """Whether the engine must consult this role during the night phase."""
-        return self in (Role.WEREWOLF, Role.SEER, Role.DOCTOR)
+        return self in (Role.WEREWOLF, Role.SEER, Role.DOCTOR, Role.WITCH)
 
     @property
     def summary(self) -> str:
@@ -66,6 +67,12 @@ def summary(self) -> str:
         "killed at night — you take one living player down with you. You "
         "win with the village."
     ),
+    Role.WITCH: (
+        "You hold two one-time potions. Each night you learn who the "
+        "werewolves attacked; you may use a healing potion to save them, "
+        "and/or a poison potion to kill any one player. You win with the "
+        "village."
+    ),
 }
 
 
@@ -89,6 +96,8 @@ def standard_setup(n_players: int) -> list[Role]:
         roles.append(Role.DOCTOR)
     if village_seats >= 4:
         roles.append(Role.HUNTER)
+    if village_seats >= 5:
+        roles.append(Role.WITCH)
 
     roles += [Role.VILLAGER] * (n_players - len(roles))
     return roles

deepwolf/game/state.py

@@ -74,6 +74,8 @@ class GameState:
     day: int = 0
     phase: Phase = Phase.SETUP
     winner: Faction | None = None
+    witch_heal_used: bool = False
+    witch_poison_used: bool = False
 
     # ---- construction -----------------------------------------------------
     @classmethod