Fix Codex provider live progress in built app

[100yenadmin]

Summary

• stream immediate engine-owned progress narration from the Codex DM wrapper during opening and after accepted player moves
• ask the Codex DM provider to emit one short live log_event(kind=\"narration\") progress beat before longer work
• align the handoff gate with the live /session-surface narration source when final chat has not landed yet
• keep wrapper-authored progress setting-agnostic and rotate move-progress text so longer play does not echo the same line every turn

Product Evidence

• Browser loop previously proved private art, Alfira as active actor, enabled actions, accepted /move, live progress, and final DM response for this slice.
• Same-SHA handoff on current head 76d5171 passed with handoff_score=100, dirty false, and zero blockers.
• Handoff gates passed on 76d5171: web scripted smoke, built dist/WorldOS.app scripted smoke, and built dist/WorldOS.app Codex-provider playtest, all with zero evidence gaps.
• This is not a release verdict; full five-persona RRI remains required.

Tests

• bash -n scripts/play_codex_dm.sh && git diff --check
• python3 -m pytest qa/test_macos_app_static.py qa/test_app_handoff_gate.py viewer/tests/test_live_narration_stream.py -q -> 46 passed
• uv run --directory servers/engine python -m pytest tests/test_codex_provider_wrapper.py -q -p no:xdist -> 22 passed
• python3 qa/app_handoff_gate.py --run-id codex-live-progress-handoff-76d5171 --web-beats 5 --built-beats 5 --codex-moves 1 --art-root <local private-art checkout> --scripted-budget 1.00 --codex-budget 3.00 --timeout 90 --codex-timeout 240 -> passed, handoff_score 100

Licensing / CLA

• I have the right to submit this work under the repository license.
• This PR does not add confidential, private-art, credential, VM access, or restricted operational material.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR integrates live progress narration detection into app handoff validation and adds provider-side live progress narration beats. The gate accepts session-surface narration when chat hasn't landed; the Codex DM wrapper emits immediate opening/move narration and tests/docs are updated to verify the behavior.

Changes

Live Progress Narration Detection and Provider Implementation

Layer / File(s)	Summary
Narration detection helper and validation extension qa/app_handoff_gate.py	session_surface_has_narration() helper scans session_surface.recentEvents for narration/dialogue. validate_app_status() signature extended with optional session_surface to use that detection.
Gate session_surface fetch reordering and validation integration qa/app_handoff_gate.py	Initial session-surface fetch moved before validate_app_status() in drive_moves(), the fetched surface is passed into validation, and fetch failures return immediately with the existing no_provider structure.
Validation tests for narration-based acceptance qa/test_app_handoff_gate.py	Adds tests: one asserts validate_app_status succeeds when viewer.chat_lines is zero but session_surface.recentEvents contains a narration event; the other asserts failure when narration is absent.
Codex DM provider live progress narration implementation scripts/play_codex_dm.sh	Adds LIVE_PROGRESS_LOG_RULE, opening/move progress text constants, injects the live-progress rule into opening and mid-session prompts, records immediate opening narration when HERO_CAMP is set, and logs move-progress narration after move detection.
Contract test for live progress events qa/test_macos_app_static.py, viewer/openworlds/app.jsx	New contract test inspects play_codex_dm.sh and app.jsx for live progress logging constants, required log/narration ordering, rule occurrence counts, absence of restricted messages, and viewer messaging about immediate engine progress writes and turn liveness.
Timeout logic documentation update viewer/openworlds/app.jsx	Clarifies adaptive recovery “stuck” timeout explanation (comments only; no runtime changes).

Possibly Related PRs

• electricsheephq/WorldOS#504: Prior changes touching qa/app_handoff_gate.py that relate to session-surface validation flow.
• electricsheephq/WorldOS#500: Related changes to scripts/play_codex_dm.sh affecting DM narration/progress logging rules.
• electricsheephq/WorldOS#394: Earlier work on validate_app_status() and session-surface narration/dialogue handling.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hopped the gate where session whispers play,
Found tiny beats that keep the turn awake,
A narration pulse that lights the open way,
Provider hums and tests confirm the wake.
Hooray — the rabbit dances, sings, and bakes!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 "Fix Codex provider live progress in built app" directly summarizes the main change—enabling live progress narration in the Codex provider for the built app environment.
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.
Description check	✅ Passed	The PR description provides a clear summary of changes, product evidence, validation tests, and licensing confirmation that align well with the repository template requirements.

_{✏️ 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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/play_codex_dm.sh`:
- Around line 556-557: The recurring progress line comes from MOVE_PROGRESS_TEXT
passed into log_engine_narration each turn; change the usage so we rotate or
neutralize that string instead of logging the same verbatim text every time:
create a small pool/array of alternate progress variants (or a single brief
neutral phrase) and select one per move before calling
log_engine_narration("$ACTIVE_CAMPAIGN_ID", "$chosen_text"), or implement a
simple round-robin/random pick helper to derive chosen_text from
MOVE_PROGRESS_TEXT variants so the call site remains log_engine_narration with a
non-repeating message.
- Around line 471-474: OPENING_PROGRESS_TEXT currently contains hardcoded Lower
City sensory facts and is logged immediately via log_engine_narration
"$HERO_CAMP" "$OPENING_PROGRESS_TEXT" before start_world("$CLAWDND_WORLD") runs;
change OPENING_PROGRESS_TEXT to a setting-agnostic progress beat (e.g., neutral
"The party prepares to set out…" or a generic "Opening progress" message) or
build it conditionally from the active world/current_location_id after
start_world(...) so you don't commit locale-specific details, and update any
test in qa/test_app_handoff_gate.py that asserts the exact Lower City string to
check for the new neutral message or the conditional construction instead.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dd03bc5c-cbdb-4ee1-ae3f-8a83512bfc08

📥 Commits

Reviewing files that changed from the base of the PR and between 01882a0 and c61ed32.

📒 Files selected for processing (5)

• qa/app_handoff_gate.py
• qa/test_app_handoff_gate.py
• qa/test_macos_app_static.py
• scripts/play_codex_dm.sh
• viewer/openworlds/app.jsx