feat(cli): Add --remote flag hint on delete workflow failure

[YoavLev]

What changed?
Added a new constant remoteHint with a helpful message
Added the hint to these error paths (when not using --remote):
Failed to get workflow mutable state
Unable to initialize history manager
Unable to initialize execution manager
DeleteHistoryBranch error
Delete mutableState row failed
Delete current row failed

Why?
the adidition of --remote flag was not clear enough to the user.

---

Reviewer Validation

PR Description Quality (check these before reviewing code):

• "What changed" provides a clear 1-2 line summary
  • Project Issue is linked
• "Why" explains the full motivation with sufficient context
• Testing is documented:
  • Unit test commands are included (with exact go test invocation)
  • Integration test setup/commands included (if integration tests were run)
  • Canary testing details included (if canary was mentioned)
• Potential risks section is thoughtfully filled out (or legitimately N/A)
• Release notes included if this completes a user-facing feature
• Documentation needs are addressed (or noted if uncertain)

[gitar-bot]

Running post-merge workflows

🔍 CI failure analysis for fbfab7d: Integration test failures (TestActivityHeartbeatTimeouts) are unrelated to this PR's CLI error message changes. The failures appear to be flaky tests with timing/infrastructure issues.

Issue

The CI job "Golang integration test with sqlite" failed with two test failures:

• TestIntegrationSuite/TestActivityHeartbeatTimeouts (failed twice)
• TestIntegrationSuite/TestActivityHeartbeatDetailsDuringRetry (failed once)

Both tests failed with timeout-related issues during the integration test suite execution.

Root Cause

This failure is not related to the PR changes. The PR only modifies error message strings in tools/cli/admin_commands.go by adding helpful hints about the --remote flag. It does not change any business logic, test code, or runtime behavior.

The failing tests are in host/activity_test.go and relate to activity heartbeat timeout behavior. The error message "Expected activities to timeout but seeing completion instead" at line 1107 indicates a timing/flakiness issue in the test infrastructure, not a code defect introduced by this PR.

Details

Test Failure Pattern:

• TestActivityHeartbeatTimeouts failed in both runs with identical error messages
• The test expects activities to timeout but they completed successfully instead
• Error location: host/activity_test.go:1107 - assertion s.False(failWorkflow, failReason) with message "Expected activities to timeout but seeing completion instead"

Evidence this is unrelated to PR changes:

1. PR only touches tools/cli/admin_commands.go - adding string constants and modifying error messages
2. No changes to test files, activity handling, timeout logic, or any runtime code paths
3. Failing tests are integration tests for activity heartbeat behavior, which is completely unrelated to CLI error message formatting
4. The logs show context deadline exceeded errors and database locking issues ("sqlite3: database is locked"), which are infrastructure/timing related

Likely causes:

• Test flakiness due to timing sensitivity in heartbeat timeout tests
• SQLite database contention issues under test load
• Infrastructure timing issues in the CI environment

This appears to be a flaky test issue that existed before this PR.

Code Review 👍 Approved with suggestions 0 resolved / 1 findings

Clean UX improvement adding helpful --remote flag hints to CLI error messages. Changes are consistent and correctly scoped. Pre-existing defer ordering issue (potential nil panic) remains unaddressed but is outside the scope of this PR.

⚠️ Bug: Potential nil panic: defer Close() called before error check

📄 tools/cli/admin_commands.go:309

The defer histV2.Close() statement on line 309 is executed before checking if initializeHistoryManager returned an error on line 310. If the function returns an error, histV2 may be nil, and the deferred Close() call would panic when the function returns.

This is a pre-existing issue (the diff shows this line was not changed), but it's worth noting that the new error path with remoteHint could now expose this bug more frequently if users encounter initialization failures.

Suggested fix:
Move the defer after the error check:

histV2, err := getDeps(c).initializeHistoryManager(c)
if err != nil {
    return commoncli.Problem("Unable to initialize history manager"+remoteHint, err)
}
defer histV2.Close()

Note: This appears to be pre-existing code, not introduced by this PR, but the reviewer should be aware of this potential issue in the modified code path.

Rules ❌ No requirements met

Repository Rules

❌ PR Description Quality Standards: PR description incomplete: missing [How did you test it?], [Potential risks], [Release notes], and [Documentation Changes] sections. [Why?] section lacks sufficient context (only single sentence with typo). [What changed?] should be 1-2 line summary with GitHub issue link.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[gazi-yestemirova]

lgtm