Workspace startup tombstone to detect and clean partial starts (BT-969)

[jamesc]

Summary

Implements the startup tombstone approach from BT-969 to make workspace startup crash-recovery self-describing and complete.

• Write a starting sentinel file at the very beginning of start_detached_node, before spawning the BEAM node
• Remove it on successful startup (after save_node_info)
• On entry to start_detached_node, the existing remove_stale_runtime_files call now also removes starting, so if the file is present from a previous interrupted startup, all stale runtime files (node.info, port, pid, starting) are cleaned before proceeding
• New integration test: starts a node, simulates a mid-startup crash by writing starting after a kill, verifies next start_detached_node succeeds cleanly
• New unit tests: remove_stale_runtime_files removes starting tombstone, idempotent on missing files

This is additive to BT-967 — the remove_stale_runtime_files cleanup now covers all current and future runtime files via the tombstone mechanism.

Linear

https://linear.app/beamtalk/issue/BT-969/workspace-startup-tombstone-to-detect-and-clean-partial-starts

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • Improved workspace node startup reliability by automatically cleaning up incomplete state from failed startup attempts on the next start.

• Tests

  • Added integration and unit tests to verify startup state cleanup and idempotency behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 6a56e73 and c6b312c.

📒 Files selected for processing (3)

• crates/beamtalk-cli/src/commands/workspace/mod.rs
• crates/beamtalk-cli/src/commands/workspace/process.rs
• crates/beamtalk-cli/src/commands/workspace/storage.rs

---

📝 Walkthrough

Walkthrough

A startup tombstone mechanism was implemented to handle incomplete BEAM node startups. A "starting" marker file is written before node startup and removed after successful TCP readiness, enabling cleanup of partial state from interrupted startups on subsequent start attempts.

Changes

Cohort / File(s)	Summary
Integration Tests crates/beamtalk-cli/src/commands/workspace/mod.rs	Two identical integration tests added (duplicated) named test_start_detached_node_cleans_up_tombstone_integration that verify the startup tombstone is removed after successful node restart and partial state cleanup occurs.
Startup Tombstone Logic crates/beamtalk-cli/src/commands/workspace/process.rs	Added import for remove_file_if_exists. Introduced startup tombstone by writing a "starting" file before node startup and removing it after TCP readiness confirmation. Cleanup of incomplete startup state now triggers on subsequent start attempts.
Storage Utilities & Cleanup crates/beamtalk-cli/src/commands/workspace/storage.rs	Exposed remove_file_if_exists as pub(super) with enhanced error reporting. Extended remove_stale_runtime_files to include removal of the "starting" tombstone file. Added unit tests verifying tombstone removal and idempotent cleanup behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Refactor: Split workspace/mod.rs and doc.rs into focused modules (BT-640) #631 — Directly modifies the same workspace process and storage logic, introducing remove_file_if_exists and stale-runtime cleanup that this PR extends.
• Fix flaky workspace integration tests (BT-662) #646 — Modifies start_detached_node startup sequencing in process.rs, coordinating with TCP readiness and epmd handling alongside the tombstone lifecycle.
• Improve workspace module test coverage (BT-534) #469 — Adds workspace node startup integration tests exercising start_detached_node and get_or_start_workspace behavior, directly related to the test additions.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: implementing a workspace startup tombstone mechanism to detect and clean partial starts, with direct reference to the issue (BT-969).
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch worktree-BT-969

---

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