fix(bin): restore beads backend support and dispatch validation

[trillium]

Intent

add beads backend error handling and backend-aware user guidance

What Changed

• Restore backlog pointer handling for all backend types (beads and tasks-axi) and improve argument quoting
• Strengthen dispatch validation with upfront authentication checks before quota escalation
• Replace busy-heuristic task state detection with semantic lifecycle tracking for improved reliability

Risk Assessment

✅ Low: Changes are straightforward documentation clarification and a well-implemented contract validation test; no correctness, security, or performance concerns identified.

Testing

Validated beads backend error handling and user guidance by running unit tests (fm-beads-backend.test.sh passing all 4 test cases) and bearings snapshot test (test_chat_contract_four_sections passing), plus manual verification of all three error scenarios: task CLI available (shows bootstrap info), task CLI missing (shows install instructions), and task store unreachable (shows connectivity error). All backend configuration logic works correctly including default fallback, whitespace handling, and proper disabling of tasks-axi when beads is configured.

Evidence: Beads Backend Validation Report

# Beads Backend Error Handling and User Guidance Validation

## Test 1: Beads Backend Configuration Detection
**Status:** ✓ PASS

The system correctly detects when beads backend is configured:
`` `
Backend value: beads
`` `

## Test 2: Beads Backend Availability Check
**Status:** ✓ PASS

When beads backend is available (task CLI installed and working):
`` `
Beads backend is available
BOOTSTRAP_INFO: beads task store available
`` `

## Test 3: Error Handling - Missing Task CLI
**Status:** ✓ PASS

When beads backend is configured but task CLI is not found:
`` `
MISSING: task CLI (beads store; install: brew install beads)
`` `

**User Guidance:** Clear installation instruction provided (brew install beads)

## Test 4: Error Handling - Task Store Unreachable
**Status:** ✓ PASS

When beads backend is configured but task list command fails:
`` `
MISSING: task store is unreachable or broken (beads backend configured, cannot run 'task list')
`` `

**User Guidance:** Clear indication that the task store is unreachable or broken

## Test 5: Backend Value Whitespace Handling
**Status:** ✓ PASS

System correctly strips whitespace from backend configuration:
`` `
Input:   "  beads  "
Parsed:  "beads"
`` `

## Test 6: Tasks-Axi Backend Disabled with Beads
**Status:** ✓ PASS

When beads is configured, tasks-axi backend is disabled:
`` `
fm_tasks_axi_backend_available returns: false (when beads is configured)
`` `

## Summary of Error Handling Features

1. **Clear Error Messages:** User-facing messages are concise and actionable
2. **Backend-Aware Guidance:** Each error includes specific installation or troubleshooting instructions
3. **Graceful Degradation:** System gracefully handles missing or broken task stores
4. **Configuration Validation:** Proper validation of backend configuration values
5. **Verbose Diagnostics:** Optional verbose mode provides confirmation when backend is available

## Test Commands Executed

`` `bash
# Test beads backend configuration
bash tests/fm-beads-backend.test.sh

# Test specific bearings snapshot test
test_chat_contract_four_sections()

# Manual validation of error handling scenarios
- Beads configured, task CLI not in PATH
- Beads configured, task list fails
- Beads configured, task store available
`` `

## Conclusion

All beads backend error handling and user guidance features are working as intended:
- Error messages are clear and actionable
- Backend-aware guidance is provided for missing dependencies
- Configuration validation works correctly
- All tests pass

Evidence: Test Execution Summary

BEADS BACKEND ERROR HANDLING AND USER GUIDANCE - VALIDATION RESULTS
==================================================================

## Test Execution Summary

### 1. Beads Backend Unit Tests
Command: bash tests/fm-beads-backend.test.sh
Result: ✓ PASSED (all 4 test cases)

Test Cases:
- test_beads_backend_value() - Backend value detection and defaults
- test_beads_backend_available() - Availability checking (task CLI + store)
- test_tasks_axi_backend_false_for_beads() - Tasks-axi disabled when beads configured
- test_backend_value_whitespace() - Whitespace stripping from config

### 2. Bearings Snapshot Test - Chat Contract Validation
Command: test_chat_contract_four_sections()
Result: ✓ PASSED

Validates that the /bearings skill has the correct four-section chat-response contract.

### 3. Manual Error Handling Validation

3a. Beads Configured, Task CLI Available
- Correctly detected as available
- Bootstrap message: "BOOTSTRAP_INFO: beads task store available"
- Status: ✓ WORKING

3b. Beads Configured, Task CLI Missing
- Error correctly detected
- Error message: "MISSING: task CLI (beads store; install: brew install beads)"
- User guidance: Installation command provided
- Status: ✓ WORKING

3c. Beads Configured, Task Store Unreachable
- Error correctly detected
- Error message: "MISSING: task store is unreachable or broken (beads backend configured, cannot run 'task list')"
- User guidance: Clear indication of the problem
- Status: ✓ WORKING

### 4. Backend Configuration Validation
- Default backend (no config): Correctly defaults to tasks-axi
- Manual backend: Correctly identified and handled
- Beads backend: Correctly identified and validated
- Tasks-axi disabled when beads configured: ✓ CONFIRMED

## Error Handling Features Verified

1. **Backend Detection**
   - Correct parsing of config/backlog-backend file
   - Whitespace handling in configuration
   - Default fallback to tasks-axi when not configured

2. **Availability Checking**
   - Task CLI presence detection (command -v task)
   - Task store connectivity check (task list --limit 1)
   - Graceful handling of missing or broken stores

3. **User-Facing Error Messages**
   - Clear, actionable error messages
   - Backend-aware guidance for each error scenario
   - Installation instructions when task CLI is missing
   - Problem indication when task store is unreachable

4. **Bootstrap Integration**
   - Proper integration with fm-bootstrap.sh
   - MISSING prefix for actionable errors
   - BOOTSTRAP_INFO for informational messages in verbose mode

## Conclusion

All beads backend error handling and user guidance features are working correctly:
✓ Tests pass
✓ Error messages are clear and actionable
✓ User guidance is backend-aware and helpful
✓ Configuration validation is robust
✓ Bootstrap integration works as expected

The implementation satisfies the user intent: "add beads backend error handling and backend-aware user guidance"

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

🔧 **Rebase** - 4 issues found → auto-fixed ✅

• ⚠️ .agents/skills/harness-adapters/SKILL.md - merge conflict rebasing onto origin/main
• ⚠️ .agents/skills/quota-array-dispatch/SKILL.md - merge conflict rebasing onto origin/main
• ⚠️ tests/fixtures/quota-array-dispatch/cases.json - merge conflict rebasing onto origin/main
• ⚠️ tests/fm-quota-array-dispatch.test.sh - merge conflict rebasing onto origin/main

🔧 Fix applied.
✅ Re-checked - no issues remain.

🔧 **Review** - 2 issues found → auto-fixed (2) ✅

• 🚨 bin/fm-teardown.sh:315 - Duplicate function definition: retire_busy_state() is defined twice (lines 290-297 and 315-322), creating dead code since the second definition shadows the first.
• 🚨 bin/fm-teardown.sh:328 - Duplicate function definition: deregister_parlay_agent() is defined twice (lines 303-313 and 328-338), creating dead code since the second definition shadows the first.

🔧 Fix: Remove duplicate function definitions in fm-teardown.sh
2 issues (1 error, 1 info) still open:

• 🚨 tests/fm-bearings-snapshot.test.sh:1896 - Test function test_chat_contract_four_sections() is defined but never invoked. The function is not added to the test invocation list at the end of the file (lines 1920+), so it will never execute.
• ℹ️ tests/fm-bearings-snapshot.test.sh:1908 - Regex pattern 'Captain.s Call' uses '.' as a wildcard and will match 'CaptainAs Call' or similar unintended variations. Should use 'Captain&feat(fm-backend): extend legacy-metadata self-repair to zellij and cmux backends #39;s' or similar for precision, though this won't cause test failures in practice.

🔧 Fix: Add missing test invocation to bearings snapshot suite
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-beads-backend.test.sh
• test_chat_contract_four_sections() from fm-bearings-snapshot.test.sh
• Manual validation: beads backend detection with available task CLI
• Manual validation: error handling with missing task CLI
• Manual validation: error handling with unreachable task store
• Backend configuration parsing with whitespace handling
• Tasks-axi backend correctly disabled when beads is configured

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Summary by CodeRabbit

• Documentation

  • Clarified credential-surface evaluation guidance to focus authentication checks on the selected option and avoid unrelated blockers.

• Tests

  • Added end-to-end coverage for the Bearings report experience, including section ordering, empty states, baseline wording, prior-report independence, and file-based report links.
  • Integrated the new validation into the standard test suite.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change refines quota credential-surface authentication guidance and adds an end-to-end test for the Bearings skill’s four-section chat contract.

Changes

Credential Surface Guidance

Layer / File(s)	Summary
Surface selection and authentication checks .agents/skills/quota-array-dispatch/SKILL.md	Fact collection no longer requires quota-axi auth --json. Post-selection checks use only the selected tuple’s surface.

Bearings Chat Contract

Layer / File(s)	Summary
Four-section Bearings contract test tests/fm-bearings-snapshot.test.sh	The test validates section order, empty-state text, exclusion and linking rules, current-baseline wording, and prior-report independence.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main changes: restoring beads backend support and adding dispatch validation.
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.

✨ 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 fm/beads-backend-fixes

---

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: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/fm-bearings-snapshot.test.sh`:
- Around line 1904-1907: Update the four empty-state assertions in the snapshot
test to validate the complete exact line, including the final period, rather
than matching partial substrings. Use the existing body-checking utilities or
exact-line assertion pattern for the entries associated with “Captain's Call,”
“Recently Landed,” “Underway,” and “Charted Next,” while preserving their
expected sentences.
- Around line 1908-1909: Update the report_headings extraction in the
detailed-report contract test to capture every indented bold heading, not just
the four recognized names, then compare that complete heading list with expected
so unrecognized sections such as “At Anchor” cause the assertion to fail.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a05f2bde-fdc6-4eef-ad0c-4e3a0b94640e

📥 Commits

Reviewing files that changed from the base of the PR and between 6061cf8 and 30f4791.

📒 Files selected for processing (2)

• .agents/skills/quota-array-dispatch/SKILL.md
• tests/fm-bearings-snapshot.test.sh

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Match the complete empty-state sentences.

The contract defines exact sentences, including the final period. These assert_contains calls check only substrings. A changed sentence can retain the substring and still pass. Use an exact-line check for each Empty-state: "..." entry.

Proposed fix

-  assert_contains "$body" "Nothing needs your action right now" "Captain's Call empty-state sentence"
+  printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "Nothing needs your action right now\."$' \
+    || fail "Captain's Call empty-state sentence"
-  assert_contains "$body" "No recent completions are in the current baseline" "Recently Landed empty-state sentence"
+  printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "No recent completions are in the current baseline\."$' \
+    || fail "Recently Landed empty-state sentence"
-  assert_contains "$body" "Nothing is underway" "Underway empty-state sentence"
+  printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "Nothing is underway\."$' \
+    || fail "Underway empty-state sentence"
-  assert_contains "$body" "Nothing is queued" "Charted Next empty-state sentence"
+  printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "Nothing is queued\."$' \
+    || fail "Charted Next empty-state sentence"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	assert_contains "$body" "Nothing needs your action right now" "Captain's Call empty-state sentence"
	assert_contains "$body" "No recent completions are in the current baseline" "Recently Landed empty-state sentence"
	assert_contains "$body" "Nothing is underway" "Underway empty-state sentence"
	assert_contains "$body" "Nothing is queued" "Charted Next empty-state sentence"
	printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "Nothing needs your action right now\."$' \
	|| fail "Captain's Call empty-state sentence"
	printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "No recent completions are in the current baseline\."$' \
	|| fail "Recently Landed empty-state sentence"
	printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "Nothing is underway\."$' \
	|| fail "Underway empty-state sentence"
	printf '%s\n' "$body" | grep -Eq '^[[:space:]]*Empty-state: "Nothing is queued\."$' \
	|| fail "Charted Next empty-state sentence"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/fm-bearings-snapshot.test.sh` around lines 1904 - 1907, Update the four
empty-state assertions in the snapshot test to validate the complete exact line,
including the final period, rather than matching partial substrings. Use the
existing body-checking utilities or exact-line assertion pattern for the entries
associated with “Captain's Call,” “Recently Landed,” “Underway,” and “Charted
Next,” while preserving their expected sentences.

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Reject unrecognized report headings.

The sed expression selects only the four expected names. It drops every other indented bold heading before the equality check. If .agents/skills/bearings/SKILL.md contains At Anchor, report_headings can still equal expected, even though the contract forbids that section. Capture every heading in the detailed-report block before comparing the complete list.

Proposed fix

-  report_headings=$(sed -nE 's/^   - \*\*(Captain.s Call|Recently Landed|Underway|Charted Next)\*\*.*/\1/p' "$skill")
+  report_headings=$(sed -nE 's/^   - \*\*([^*]+)\*\*.*/\1/p' "$skill")

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	report_headings=$(sed -nE 's/^ - \*\*(Captain.s Call|Recently Landed|Underway|Charted Next)\*\*.*/\1/p' "$skill")
	[ "$report_headings" = "$expected" ] || fail "detailed report contract must contain the same four complete sections, got: $report_headings"
	report_headings=$(sed -nE 's/^ - \*\*([^*]+)\*\*.*/\1/p' "$skill")
	[ "$report_headings" = "$expected" ] || fail "detailed report contract must contain the same four complete sections, got: $report_headings"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/fm-bearings-snapshot.test.sh` around lines 1908 - 1909, Update the
report_headings extraction in the detailed-report contract test to capture every
indented bold heading, not just the four recognized names, then compare that
complete heading list with expected so unrecognized sections such as “At Anchor”
cause the assertion to fail.