fix(api): persist final heartbeat state after execution settlement

[mmabrouk]

Context

After an agent finished, another browser could keep showing activity dots because the project session list still reported it as running. The individual session snapshot already said idle. The heartbeat database guard treated every execution row as terminal, although approval continuations create active rows upfront, and rejected the final idle update after settlement.

Changes

Treat only execution rows with a terminal outcome as settled. Allow the final non-running heartbeat to mirror completion after settlement, while retaining the same-turn and previously-live row checks. Late running heartbeats still cannot revive a settled execution or a row collapsed by the watchdog.

Tests

All eight real Postgres tests in the affected persistence suite pass. New cases cover active continuation rows, final idle updates, late running updates, replaced turns, and collapsed rows. The existing blocked-on-watchdog race also passes. Ruff format and lint pass.

A live local browser turn completed a read tool and returned its exact final answer once. The session detail, project list, and snapshot agreed it was idle, and the observer's activity dots disappeared with the frontend unchanged.

What to QA

Open the same session in two browsers, run a tool and let it finish, and verify both clients settle. Repeat after an approval continuation. Stop and a later turn must still preserve session ownership.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
agenta-documentation	Ready	Preview	Sep 6, 2026 12:36am UTC

[mmabrouk]

🤖 The AI agent says: @coderabbitai review

Please review e3cecf0 for heartbeat completion correctness and preserved takeover/watchdog fences. Eight real Postgres regressions pass, including the blocked-on-sweep race. Live local browser verification confirms the session list now agrees with the idle snapshot and the observer activity indicator clears.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Team

Run ID: 3f7de865-9d1d-42b9-8a40-eb4f78757e6f

📥 Commits

Reviewing files that changed from the base of the PR and between 186b96d and e3cecf0.

📒 Files selected for processing (2)

• api/oss/src/dbs/postgres/sessions/streams/dao.py
• api/oss/tests/pytest/unit/sessions/test_watchdog_collapse_persistence.py

Included review availability: Your plan provides up to 8 included reviews per hour; 5 remain after this review.

---

📝 Summary

Summary by CodeRabbit

• Bug Fixes

  • Final idle state updates now persist after an execution has settled.
  • Active updates can no longer revive executions that have already ended.
  • Terminal status is recognized only when a terminal outcome has been recorded.

• Tests

  • Added coverage for active, settled, collapsed, and replaced-turn execution scenarios.

Walkthrough

The session stream mirror now recognizes terminal executions only when terminal_outcome is recorded. Settling streams can persist final idle beats, while active beats remain blocked after execution completion. Integration tests cover accepted and rejected update states.

Changes

Session stream settlement persistence

Layer / File(s)	Summary
Settlement-aware update predicate and integration coverage api/oss/src/dbs/postgres/sessions/streams/dao.py, api/oss/tests/pytest/unit/sessions/test_watchdog_collapse_persistence.py	SessionStreamsDAO.update requires a recorded terminal outcome and allows updates for settling streams. The parametrized integration test verifies active, settled, collapsed, and replaced-turn cases.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to e3cec

This change allows a session’s final idle heartbeat to persist after execution settlement while continuing to prevent late active updates from reviving settled, replaced, or watchdog-collapsed sessions. The covered persistence cases show no remaining merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 60.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the main change: persisting the final heartbeat state after execution settlement.
Description check	✅ Passed	The description directly explains the heartbeat settlement bug, the code changes, the tests, and the QA steps.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/release-1152-heartbeat-mirror

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

@mmabrouk I will review commit e3cecf05ec1d4f5bb9b0770803408bc821c79608 with focus on heartbeat completion and takeover/watchdog fences.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[github-actions]

Railway Preview Environment

Status	Destroyed (PR closed)

Updated at 2026-09-06T02:48:55.189Z