HACK-434: Harden runtime, sessions, and remote beta flows

[roodboi]

Summary

• land the runtime/session/remote beta hardening changes from the Symphony branch
• carry the stream docs and planning artifacts for the runtime/session/remote beta work
• expose the branch for review instead of leaving it stranded as an unreviewed remote

Notes

• this branch still needs normal PR review and verification against current main
• HACK-433 has no remaining diff against main, so there is no corresponding PR to open

Summary by CodeRabbit

• Documentation

  • Docker Desktop now prioritized as default container runtime option
  • Remote node features and dispatch workflows labeled as beta
  • Session management documented as tmux-first preference

• Improvements

  • Enhanced diagnostic and repair guidance in hack daemon status and hack doctor commands
  • Crash capture now includes Docker Desktop-specific diagnostics alongside OrbStack support

[coderabbitai]

Warning

Rate limit exceeded

@roodboi has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 20 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a86912a5-c7e6-423e-a42f-de25a19cf42a

📥 Commits

Reviewing files that changed from the base of the PR and between ef8f863 and 9185686.

📒 Files selected for processing (27)

• .github/workflows/release-prepare.yml
• packages/cli/index.ts
• packages/db/tests/smoke.test.ts
• packages/db/tsconfig.json
• services/auth-broker/tests/config.test.ts
• services/auth-broker/tsconfig.json
• src/cli/prerequisites.ts
• src/commands/daemon.ts
• src/commands/global.ts
• src/control-plane/extensions/linear/commands.ts
• src/control-plane/extensions/linear/project-artifacts.ts
• src/control-plane/extensions/tickets/commands.ts
• src/control-plane/extensions/tickets/domain.ts
• src/control-plane/extensions/tickets/normalized-model.ts
• src/control-plane/extensions/tickets/provenance.ts
• src/daemon/runtime-cache.ts
• src/daemon/status.ts
• src/lib/config-paths.ts
• src/lib/runtime-projects.ts
• src/mcp/agent-docs.ts
• tests/config-paths.test.ts
• tests/daemon-status.test.ts
• tests/linear-commands.test.ts
• tests/project-views.test.ts
• tests/runtime-cache.test.ts
• tests/tickets-git-channel.test.ts
• tsconfig.json

Walkthrough

This pull request marks remote execution, node management, and dispatch features as beta, implements tmux-first session semantics, introduces Docker runtime detection and repair guidance generation for daemon/doctor commands, and adds comprehensive test coverage across new and modified functionality.

Changes

Cohort / File(s)	Summary
Documentation Updates README.md, docs/README.md, docs/cli.md, docs/sessions.md, docs/guides/remote-node-*, docs/plans/*	Updated README guidance to prioritize Docker Desktop, re-label remote node features as beta, and mark hack remote setup as beta. Enhanced docs/cli.md with beta banners for hack node, hack dispatch, hack remote. Updated session docs to describe tmux-first selection strategy. Added two new design/implementation plan documents detailing Docker guidance, session naming, and beta surface labeling.
Docker Runtime Guidance System src/lib/runtime-guidance.ts	New module providing Docker backend detection (detectDockerBackend), failure text extraction (extractDockerFailureText), repair guidance generation (formatDockerConnectionGuidance, buildDockerStartStep), and Docker reachability probing (buildDockerStatusProbe). Supports macOS (Docker Desktop/OrbStack via bundle detection) and Linux (systemd backend detection).
Daemon & Doctor Enhancements src/commands/daemon.ts, src/commands/doctor.ts, src/daemon/status.ts	Integrated Docker diagnostics into daemon status and doctor checks. buildDaemonRepairMessage now generates backend-aware repair guidance for stale/crashed daemon states, including launchd exit codes and Docker startup hints. Enhanced doctor to derive Docker backend and extract failure text when docker info fails. Updated daemon.ts to emit repair_hint in JSON and use computed repair messages for logging.
Session Management & Naming src/commands/session.ts, src/mux/session-names.ts, src/commands/project.ts	Added tmux-first session semantics and centralized session naming via buildSessionName and getNextNumericSessionSuffix. Introduced buildLegacySessionName for backward compatibility with ":" delimiter. Updated parseSessionBase to recognize both "--" and ":" delimiters. Modified project.ts lifecycle session resolver to use legacy naming for compatibility.
Beta Labels for Remote Features src/commands/remote.ts, src/commands/node.ts, src/commands/dispatch.ts	Updated CLI summary strings to prefix remote, node, and dispatch commands with "Beta:" label, indicating ongoing hardening and feature maturity.
Utility & Runtime Guidance src/lib/config-paths.ts, src/lib/project-views.ts, src/mcp/agent-docs.ts, src/commands/crash-capture.ts	Modified resolveGlobalConfigPath to prefer process.env.HOME. Enhanced matchesHackSessionName to recognize both legacy ":" and new "--" session naming formats. Expanded crash-capture to include Docker Desktop macOS logging and process capture. Updated agent docs snippet to label remote/multi-node as beta and describe tmux-first sessions.mux=auto behavior.
Test Suite tests/cli-command.test.ts, tests/config-paths.test.ts, tests/crash-capture.test.ts, tests/daemon-status.test.ts, tests/global-command.test.ts, tests/project-views.test.ts, tests/runtime-guidance.test.ts, tests/session-names.test.ts	Added comprehensive test coverage: CLI command verification for "tmux-first" and "Beta" labels, Docker backend detection and guidance formatting across macOS/Linux, daemon repair message generation, session naming (both legacy and new delimiters), config path resolution, crash capture macOS probes, and project view session matching. Updated existing tests to reflect new test prerequisites.

Sequence Diagram

sequenceDiagram
    actor User
    User->>+Doctor: hack doctor
    Doctor->>+DockerProbe: buildDockerStatusProbe()
    DockerProbe->>DockerProbe: Run 'docker info'
    DockerProbe-->>-Doctor: {reachable, result}
    
    alt Docker Unreachable
        Doctor->>+DetectBackend: detectDockerBackend()
        DetectBackend->>DetectBackend: Check platform bundle paths<br/>(macOS: /Applications/Docker.app, /Applications/OrbStack.app)<br/>(Linux: systemctl)
        DetectBackend-->>-Doctor: DockerBackend | null
        Doctor->>+ExtractFailure: extractDockerFailureText(stderr, stdout)
        ExtractFailure-->>-Doctor: failure text
        Doctor->>+FormatGuidance: formatDockerConnectionGuidance({backend, failureText})
        FormatGuidance-->>-Doctor: guidance string
    else Docker Reachable
        Doctor->>Doctor: Continue normal checks
    end
    Doctor-->>-User: guidance + status report

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

---

Possibly related PRs

• Handle missing mux binaries gracefully #12: Modifies daemon status rendering, doctor checks, and project-view session matching logic with overlapping concerns around daemon guidance and session handling.
• Review session management workflow #8: Introduces related session naming utilities and session command flow modifications that directly align with the new tmux-first semantics and -- delimiter changes.
• feat: Extension system, Remote Gateway, macOS Desktop App, and comprehensive documentation #2: Overlaps on daemon/doctor/runtime guidance refactoring, remote command surfaces, session naming infrastructure, and runtime detection utilities.

---

Poem

🐰 Through Docker's maze and daemon halls,
This rabbit hops with tmux in sight,
When guidance glows with backend light,
Beta features answer calls,
With repair tips woven tight—
The warren thrives, all paths take flight! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 15.79% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly references the main objective of the PR (HACK-434 ticket) and accurately summarizes the primary changes: hardening runtime, sessions, and remote beta flows across documentation and implementation modules.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch symphony/HACK-434-program-runtime-sessions-and-remote-beta-hardeni

---

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.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: cf8236c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR