docs(orchestration): document runtime outage delivery

[innocarpe]

Description

Document the delivery and recovery contract for orchestration commands during runtime outages.

Focused fix

• In scope: explain direct runtime delivery, the non-retry behavior on transport loss, the runtime_unavailable error, and the distinction from a reachable ask timeout.
• Out of scope: changing transport retry behavior, queueing lifecycle messages, or altering orchestration state transitions.

Preserves

• Runtime behavior is unchanged; the guide records the existing contract and tells workers/coordinators how to recover without treating a failed send as delivered.

Evidence

• Test: pnpm exec vitest run --config config/vitest.config.ts config/scripts/orchestration-skill-guidance.test.mjs
• Bundled guide verification: pnpm run verify:bundled-skill-guides
• Formatting: pnpm exec oxfmt --check skill-guides/orchestration.md config/scripts/orchestration-skill-guidance.test.mjs
• Changed-code quality passed with 0 new findings.

User-regression-tradeoffs

• The guide now distinguishes a quiet wait from a transport outage so coordinators do not silently lose a worker completion; no command behavior or retry policy changes.

Fixes #12986

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1eece64c-8a13-49c2-bab8-0760a69c455a

📥 Commits

Reviewing files that changed from the base of the PR and between 595097b and fb1b42b.

📒 Files selected for processing (3)

• config/scripts/orchestration-skill-guidance.test.mjs
• skill-guides/orchestration.md
• src/cli/bundled-skill-guides.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• src/cli/bundled-skill-guides.ts
• skill-guides/orchestration.md
• config/scripts/orchestration-skill-guidance.test.mjs

---

📝 Walkthrough

Walkthrough

The orchestration guide documents runtime outage behavior, including non-durable sends and asks, runtime_unavailable failures, lifecycle message retries, and timeout distinctions. The bundled guide includes the same section. A test verifies these requirements and the recommended state inspection commands.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the change and evidence but omits several required template sections, including AI review, security audit, screenshots, testing checklist, and notes.	Add the required template headings and content, including AI review and cross-platform checks, security audit, visual-change statement, testing checklist, and notes.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: documenting orchestration runtime outage delivery behavior.
Linked Issues check	✅ Passed	The documentation and regression test address the linked issue's delivery, recovery, error distinction, timeout, and state-inspection requirements.
Out of Scope Changes check	✅ Passed	The changes are limited to orchestration documentation, its bundled representation, and focused regression coverage, with no unrelated behavior changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

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]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d43d8a4f-bcaa-44e9-bbce-4e718827a980

📥 Commits

Reviewing files that changed from the base of the PR and between 7e60b33 and 7142ad7.

📒 Files selected for processing (3)

• config/scripts/orchestration-skill-guidance.test.mjs
• skill-guides/orchestration.md
• src/cli/bundled-skill-guides.ts

[innocarpe]

Sync update (fb1b42bbde)

Addressed review: runtime_unavailable recovery now distinguishes ask from retryable lifecycle signals and requires the exact non-consuming recovery check/message ID before creating another question. Validation: 21 guide tests, bundled-guide verification, and changed-code quality passed.

• Commit: fb1b42bbde45cd3486747612cacf25d21a9a1801
• Upstream: docs(orchestration): document runtime outage delivery #12997
• Fork portfolio: [upstream #12997] docs(orchestration): document runtime outage delivery innocarpe/orca#157

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.