Refresh stopping heartbeat during teardown

[kjgbot]

Summary

• refresh the stopping heartbeat at concrete agent teardown progress points so clean multi-agent shutdown stays fresh for the external reaper
• keep stale stopping heartbeats reapable so wedged teardown detection is preserved
• add regression coverage for progressing teardown and stale-stopping reaper behavior

Validation

• npm run typecheck:node
• npx vitest run packages/factory-sdk

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3a094286-ca61-4654-b7dd-22396c35b995

📥 Commits

Reviewing files that changed from the base of the PR and between 96e6324 and 36ba95a.

📒 Files selected for processing (3)

• packages/factory-sdk/src/orchestrator/factory.test.ts
• packages/factory-sdk/src/orchestrator/factory.ts
• packages/factory-sdk/src/orchestrator/reaper.test.ts

---

📝 Walkthrough

Walkthrough

The PR refactors factory shutdown to explicitly coordinate heartbeat freshness during graceful agent termination. A new stopping-heartbeat activation flag gates conditional heartbeat writes before and after fleet release, ensuring the heartbeat remains current through multi-step teardown and orphan reaping. Tests validate heartbeat freshness across the full shutdown sequence and verify that stale stopping heartbeats are properly detected and reaped.

Changes

Graceful Shutdown with Stopping Heartbeat Coordination

Layer / File(s)	Summary
Stopping heartbeat state and refresh methods packages/factory-sdk/src/orchestrator/factory.ts	Introduces #stoppingHeartbeatRefreshActive flag to track activation, changes #stopLiveHeartbeat to return boolean, and adds #refreshStoppingHeartbeat() method that conditionally writes a stopping heartbeat while suppressing errors.
Stop lifecycle with stopping heartbeat activation packages/factory-sdk/src/orchestrator/factory.ts	stop() now captures the boolean result of #stopLiveHeartbeat('stopping') and clears the activation flag in a finally block, explicitly managing the stopping-heartbeat refresh window across teardown.
Heartbeat refresh during agent release and termination packages/factory-sdk/src/orchestrator/factory.ts	In the context === 'stop' path of #releaseAndTerminateAgents, heartbeat refresh is called before terminating PIDs and again after fleet release attempt; both calls are gated by the activation flag, and fleet release failures are logged without blocking subsequent refresh.
Shutdown behavior validation packages/factory-sdk/src/orchestrator/factory.test.ts, packages/factory-sdk/src/orchestrator/reaper.test.ts	New FactoryLoop test verifies heartbeat freshness through multi-agent teardown and orphan reaping; new reaper test confirms that stale stopping heartbeats are correctly identified and reaped with termination signals.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• AgentWorkforce/pear#253: Extends the orphan reaper flow that this PR now coordinates with stopping heartbeat refresh during factory shutdown.
• AgentWorkforce/pear#248: Centers on factory loop teardown and heartbeat semantics at shutdown; overlaps with stopping-heartbeat coordination and liveness logic.
• AgentWorkforce/pear#276: Implements the live daemon heartbeat and stopping/updatedAtMs behavior that this PR now coordinates during shutdown.

Poem

🐰 The heartbeat stays alive through all the teardown's strife,
Fresh refreshes guard the shutdown, keeping facts of life,
No orphan left behind, reaping clean and kind,
A graceful goodbye loop—heartbeats so refined! 💙✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Refresh stopping heartbeat during teardown' directly and concisely describes the main technical change: updating heartbeat refresh behavior during the shutdown/teardown process.
Description check	✅ Passed	The description is directly related to the changeset, covering the three key aspects: heartbeat refresh during teardown, stale heartbeat reaping, and test coverage additions that align with the file changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch factory-sdk-stopping-heartbeat-sb-impl3

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed due to a network error.

---

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 and usage tips.}

[agent-relay-code]

pr-reviewer could not complete review for #290 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #290 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #290 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #290 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #290 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #290 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.