fix(play): DM resolver always writes non-empty player-facing narration per beat (Addresses #357)

[100yenadmin]

Root cause (file:line)

The play/QA resolver records the DM turn's final reply text to the player-facing /chat panel. That reply text is extracted as jq -rs 'map(select(.type=="result"))[-1].result // ""':

• scripts/play.sh:191 (dm_turn) → written at scripts/play.sh:319 via chatlog dm "$DMSG" (beat loop) and :274 (opener).
• scripts/play_party.sh:224 (turn dm) → written at :342 (opener), :380 (after intros), :442 (beat loop).
• Same pattern in qa/run_duo.sh:101 → :163/:212, and qa/run_party.sh:180/187 → :297/:318.

When a DM turn ends on a tool call (its last act was log_event / roll / advance_time) or a bare 3rd-person status line, that final result is empty/whitespace. The engine work still succeeded and the DM logged real 2nd-person prose via the engine's log_event(kind="narration"/"dialogue") tool (servers/engine/server.py:6665 → _log_session_entry → store.append_log, written to campaigns/<id>/sessions/<sid>.jsonl). That prose renders in the viewer's recentEvents (viewer/server.py:_session_event_tail_from_dir → _session_recent_events), but never reaches /chat — so chatlog dm "" writes a len=0 chat entry. A newbie sees "I acted and the game replied with nothing." It's intermittent because it depends on whether the DM's final output block was prose or a tool call (beats 0–1 wrote full prose; the [say] and [check] beats in the baseline ended on a tool/status line).

The fix (belt + suspenders)

1. Resolver fallback (primary). New shared helper clawdnd_dm_narration_or_fallback in qa/lib_beat_driver.sh: when the DM turn's final reply is empty/whitespace, recover the most recent contiguous block of player-facing prose (narration | dialogue, with dialogue keeping its speaker tag) the engine logged this beat, from the active session log — mirroring the viewer's session-log resolution (active_session_id, else session_ids[-1], same bare-filename safety). It is read-only on engine state (the engine stays the sole writer; this only reads its JSONL) and a graceful no-op (returns the original text) when there's nothing to recover — so a non-empty reply passes through verbatim and today's behavior is unchanged. Wired into scripts/play.sh + scripts/play_party.sh (the product play path the baseline used) and qa/run_duo.sh + qa/run_party.sh (the QA path — the same empty reply also feeds the behavioral gate's silent-DM check, so a tool-final-but-narrated turn is no longer mis-flagged as silence). The recovery logic lives in a standalone qa/dm_narration_fallback.py because the macOS system bash (3.2.57) mis-parses a quoted heredoc nested in $(...).

2. Prompt nudge (secondary). skills/dungeon-master/SKILL.md and the beat-resolution prompts in play.sh/play_party.sh now instruct the DM to ALWAYS end its turn on 2nd-person player-facing narration, never a tool call or a 3rd-person status line, and to also speak any prose it logged via log_event as its reply text.

Tests

servers/engine/tests/test_dm_narration_fallback.py (runs in the existing engine CI lane) writes the session log via the engine's own writer (store.append_log + models.SessionLogEntry, so it validates the exact on-disk format) and exercises the real fallback script: recovers the trailing prose block (skipping older beats + roll/system/combat bookkeeping), passes non-empty replies through, no-ops on missing/bookkeeping-only/corrupt logs, bounds a fat multi-paragraph block, and rejects a path-traversal session id. 7/7 pass locally (single-process, 0.55s).

Verification (do NOT close on merge)

Do NOT close #357 on merge — verify on the NEXT build's .app baseline: a [say] beat and a [check] beat must both produce non-empty 2nd-person narration in /chat.

Constraints honored: isolated worktree off origin/main; engine (servers/engine) is the sole writer — this is a harness/resolver/skill fix only; additive + invariant-safe.

Summary by CodeRabbit

• New Features

  • Dungeon Master narration/dialogue now automatically recovers from engine logs when direct replies are empty, preventing silent or blank outputs during tool calls or system operations.

• Bug Fixes

  • DM turns no longer appear silent when resolving on tool calls or non-prose operations.

• Documentation

  • Updated DM skill instructions to require player-facing narration at the end of each turn.

• Tests

  • Added comprehensive test coverage for narration recovery logic, edge cases, and boundary conditions.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR prevents empty DM chat output when the LLM resolves player moves via tool calls without prose replies. It adds a narration recovery script that reads session event logs, a shell helper that wraps the script, integration into QA and production play runners, comprehensive test coverage validating trailing-block recovery and edge cases, and updated DM skill documentation of the output contract.

Changes

DM Narration Fallback Recovery

Layer / File(s)	Summary
Narration recovery script and test suite qa/dm_narration_fallback.py, servers/engine/tests/test_dm_narration_fallback.py	Implements dm_narration_fallback.py to read snapshot.json, safely resolve session log paths, scan JSONL logs for trailing prose blocks (narration/dialogue), cap to 6 rows, and return formatted output. Seven tests validate trailing-block recovery, non-prose-only logs, fallback to last session id, missing logs, path-traversal rejection, output bounding, and malformed snapshots.
Shell integration helper function qa/lib_beat_driver.sh	Introduces clawdnd_dm_narration_or_fallback() that returns the DM reply verbatim if non-empty; otherwise calls the Python fallback script to recover player-facing narration from the session log, returning recovered prose if available or the original reply as fallback.
QA script integrations qa/run_duo.sh, qa/run_party.sh	Post-process the DM's initial message and each beat's response with clawdnd_dm_narration_or_fallback, ensuring tool-final-but-logged-prose turns are not misclassified as silent DM output.
Production script integrations scripts/play.sh, scripts/play_party.sh	Apply narration fallback after the DM's initial turn and per-move/per-beat turns. play_party.sh sources lib_beat_driver.sh for the helper function and applies fallback at scene opening, companion intro, and beat resolution.
DM skill output contract documentation skills/dungeon-master/SKILL.md	Documents the non-negotiable contract that DM turns must end with 2nd-person player-facing narration, forbidding tool invocations and meta/status lines, and requiring mirroring of any log_event-recorded prose in the reply text.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• electricsheephq/WorldOS#357: Addresses the same root cause—empty DM replies when tool/status calls conclude beats—by implementing the narration recovery fallback mechanism from session logs.

Possibly related PRs

• electricsheephq/WorldOS#338: Both PRs enforce anti-internal-prose expectations in skills/dungeon-master/SKILL.md; this PR provides the QA/CLI recovery mechanism while the retrieved PR implements viewer-side sanitization.

Poem

🐰 A fallback for narration so fine,
When tools end turns with nary a line,
The logs hold the prose, both spoken and dear,
So players hear stories, loud and clear!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: implementing a fallback mechanism to ensure non-empty player-facing narration is written per beat when the DM resolver encounters empty final reply text.
Description check	✅ Passed	The description is comprehensive and addresses the template requirements: it explains what changed (the root cause, the fix with two components, tests, and verification), includes the required CLA checkbox section (though unchecked), and lists validation checks.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}