feat(detect): add muse agent with generic Pick blocked detection

[ohk]

Add Muse agent detection.

• manifests: src/detect/manifests/muse.toml + website/agent-detection/muse.toml (id muse v2026.08.06.1)
• runtime: src/detect/mod.rs Agent::Muse (ALL 22, SCREEN 20), lookup for muse/muse-bin/muse-code, label/executable, sound override (sidebar unchanged)
• fix waiting answer miss: Pick footer is generic 'Enter to select · ↑/↓ to move · Tab for an optional note · Esc to interrupt' – title/message can be anything. Previous rule required AND combos; now blocked pick is single generic gate 'Enter to select' (bottom_non_empty_lines(5), priority 950, visible_blocker) with working not Enter, so any Pick triggers blocked regardless of question text.

Evidence: herdr pane read --source detection (muse-spark-1.2-contributor 0.1.0) – idle YOLO/⟩, working esc to interrupt.

Replaces #2456 (closed by bot) with sidebar revert (6 files).

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ba6bcbd0-1b5a-4b6e-9095-8dba62cd9ea0

📥 Commits

Reviewing files that changed from the base of the PR and between d79fd74 and 14d158d.

📒 Files selected for processing (16)

• docs/next/website/src/content/docs/agent-automation.mdx
• docs/next/website/src/content/docs/agents.mdx
• docs/next/website/src/content/docs/cli-reference.mdx
• docs/next/website/src/content/docs/ja/agent-automation.mdx
• docs/next/website/src/content/docs/ja/agents.mdx
• docs/next/website/src/content/docs/ja/cli-reference.mdx
• docs/next/website/src/content/docs/zh-cn/agent-automation.mdx
• docs/next/website/src/content/docs/zh-cn/agents.mdx
• docs/next/website/src/content/docs/zh-cn/cli-reference.mdx
• docs/next/website/src/data/config-reference.json
• src/config/sidebar.rs
• src/config/sound.rs
• src/detect/manifest.rs
• src/detect/manifest/tests.rs
• src/detect/manifests/muse.toml
• src/detect/mod.rs

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

• src/detect/manifest.rs
• src/config/sound.rs
• src/detect/manifests/muse.toml

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds Muse as a supported agent, detects its terminal states through a bundled manifest, adds Muse sound overrides, updates canonical-agent coverage, and documents Muse support in English, Japanese, and Chinese.

Changes

Muse detection integration

Layer / File(s)	Summary
Define the Muse agent src/detect/mod.rs, src/config/sidebar.rs, docs/next/website/src/content/docs/*	Adds Muse to agent collections, executable mappings, aliases, identification tests, canonical-agent coverage, and supported-agent documentation.
Add Muse detection rules src/detect/manifest.rs, src/detect/manifests/muse.toml, src/detect/manifest/tests.rs	Registers the Muse manifest and detects blocked, working, idle, picker, and menu states from terminal evidence.
Configure Muse sound overrides src/config/sound.rs, src/data/config-reference.json	Adds Muse sound override storage, lookup, default initialization, and configuration reference data.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 14d15

This PR adds Muse detection and broadens Pick-blocked detection to use the generic selection prompt; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant DetectionEngine
  participant MuseManifest
  participant TerminalPane
  DetectionEngine->>MuseManifest: Evaluate Muse detection rules
  MuseManifest->>TerminalPane: Inspect terminal evidence
  TerminalPane-->>MuseManifest: Return state evidence
  MuseManifest-->>DetectionEngine: Return Muse state and visibility flags

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 5 files. (11 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding Muse agent detection and generic Pick blocked detection.
Description check	✅ Passed	The description directly explains the Muse detection, manifest, runtime, sound configuration, and Pick detection changes.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 5 files. (11 skipped: 11 unsupported.)

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[kangal-bot]

Hi @ohk, thanks for your interest in contributing.

Herdr does not accept unsolicited implementation pull requests from contributors who are not listed in .github/APPROVED_CONTRIBUTORS.

The pull request author is not an approved contributor.

If you encountered a reproducible bug, report the observed behavior through the bug issue template. A report does not reserve the work or authorize a pull request; accepted fixes are normally implemented by Herdr’s maintainer-controlled agents.

Feature requests, behavior changes, and other proposals belong in GitHub Discussions. Do not open an issue merely to justify an implementation that was already written.

If a maintainer explicitly wants this implementation, they can reopen the pull request. Reopening by anyone else will be closed again automatically.

See https://github.com/herdrdev/herdr/blob/master/CONTRIBUTING.md for the contribution policy.

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 79b2bc5b-5e09-4326-8058-6f7f02062b92

📥 Commits

Reviewing files that changed from the base of the PR and between 7d77e92 and 773b4b6.

📒 Files selected for processing (6)

• src/config/sound.rs
• src/detect/manifest.rs
• src/detect/manifests/muse.toml
• src/detect/mod.rs
• website/agent-detection/index.toml
• website/agent-detection/muse.toml

[greptile-apps]

Greptile Summary

The PR adds Muse as a supported agent, including executable identification, screen-state detection, per-agent sound configuration, tests, and user documentation.

• Registers Muse in the agent and bundled-manifest registries.
• Recognizes canonical aliases and path-qualified versioned Muse binaries.
• Detects Muse idle, working, picker, approval, and menu states.
• Adds Muse sound overrides and updates localized documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/detect/mod.rs	Adds Muse identity, executable mapping, exact aliases, and path-aware recognition of versioned Muse binaries; the previously reported path and prefix issues are addressed.
src/detect/manifests/muse.toml	Defines scoped and prioritized Muse state rules; the previously reported stale-picker negative gate is now aligned with the live bottom-screen region.
src/detect/manifest/tests.rs	Covers representative Muse working, picker, approval, menu, and idle states.
src/config/sound.rs	Adds a defaulted Muse-specific sound override and maps detected Muse agents to it.
src/config/sidebar.rs	Replaces a manually maintained test list with the canonical Agent::ALL registry.
src/detect/manifest.rs	Registers the bundled Muse screen manifest.
docs/next/website/src/data/config-reference.json	Documents the Muse per-agent sound configuration key.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  P[Foreground process or argv0] --> N[Normalize extension and basename]
  N --> I{Muse executable or alias?}
  I -->|No| U[Unknown or another agent]
  I -->|Yes| M[Load Muse manifest]
  M --> S[Evaluate bottom-screen rules]
  S --> O[Idle, Working, Blocked, or Unknown]
  O --> A[Pane state and sound policy]

Loading

_{Reviews (10): Last reviewed commit: "fix(detect): prevent false muse blocked ..." | Re-trigger Greptile}

[mjdouglas]

Muse Code team member here — glad to see this. I've been validating Muse detection against the live UI from the vendor side (herdr agent read --source detection + herdr agent explain through full idle → working → blocked → idle cycles), and three findings from those captures are worth folding in before this merges:

1. pick_request_blocked's 5-line region misses the picker footer on narrow panes.
The Pick footer wraps: at narrower widths it renders as two lines (Enter to select · ↑/↓ to move · Tab for an optional / note · Esc to interrupt), and the persistent prompt chrome (── Voice input …, ⟩, rule line, status line) fills the bottom four non-empty lines. In my capture, "Enter to select" sat on the 6th non-empty line from the bottom, so bottom_non_empty_lines(5) never sees it — blocked reads as idle exactly when the agent is waiting. Widening the region (or whole_recent) fixes it; that also resolves the region mismatch Greptile flagged between this rule (5 lines) and the working rule's not-gate (8 lines).

2. idle_status_fallback on "YOLO" only works in --yolo mode.
Without the flag there's no YOLO token, and the model segment of the status line varies by build/config (it isn't always muse-spark-*), so neither is a stable anchor. The invariant is the footer's shape: model · effort · cwd — a line regex like ^\s*[A-Za-z0-9._-]+ · [a-z]+ · [~/] matched every variant I captured (including absolute cwds outside $HOME, where a ~/ token also fails).

3. The startup workspace-trust dialog reads as idle.
First launch in an untrusted directory shows Do you trust this workspace? with > 1 Trust and continue / 2 Quit — no rule matches, so it falls to the known-agent idle fallback while the agent is actually blocked. A rule on "Do you trust this workspace?" + any of "Trust and continue" / "Use Up/Down" catches it.

One smaller note: idle_prompt's '^\s*⟩\s*$' only matches an empty prompt; a second pattern for ⟩ with typed text keeps idle stable while composing (they need to be OR'd via an any gate — multiple top-level line_regex entries AND together).

Happy to share the raw captures for any of these. Separately, #2588 proposes the session-identity + resume half (muse resume <id>) as a follow-up to this — I can support that from the Muse side.

[mjdouglas]

@ohk following up on the edge-case question — a few more, all from live captures on the vendor side, roughly by impact:

1. User-opened pickers have a different footer than agent-initiated ones. /model shows ↑↓ move · enter confirm · esc go back — lowercase "enter confirm", no "Enter to select", and ↑↓ without the slash — so the generic Pick gate doesn't match it and the pane reads idle while a menu is up. Worth deciding deliberately whether user-opened menus should be blocked (they do need input, but the agent isn't waiting on an answer); if yes, that footer needs its own rule.

2. The picker selection marker is the same ⟩ glyph as the prompt. The highlighted row renders as ⟩ <model name>, so a typed-text idle pattern (^\s*⟩\s+) can match a picker row. Any such pattern should stay in a tight bottom region and be not-gated on the picker footers.

3. Typed-but-unsubmitted text breaks the empty-prompt idle rule. While composing, the prompt renders ⟩ <draft text> (wrapping to continuation lines), so '^\s*⟩\s*$' stops matching and idle falls through to the fallback. Related: submitted prompts get echoed into scrollback as ⟩ <text> lines, which is why the typed-text variant needs a small bottom region.

4. blocked_approval's prose-like words can false-positive. Muse's own replies and tool output land in the bottom-8 region right after a turn (it will happily quote "Do you want to proceed?" or "Allow" back at you in prose). Anchoring blocked on footer chrome rather than sentence words is safer.

5. Working has more shapes than Thinking: ◇/◆ Finishing up (Ns · esc to interrupt) after answering a question, and tool lines like ◆ Ran command · … · ✓ · 0.1s · ctrl+o / └ (ctrl+b to send to background). The spinner alternates ◇/◆. Your generic esc to interrupt gate covers all of these — keep it generic.

6. Startup transients: a Muse Code 0.1.0 banner and, sometimes, Your selected model is no longer available; switched to … appear above the first idle chrome. Nothing should key on them.

7. Case-sensitivity gotcha in herdr: contains matches case-insensitively but regex/line_regex don't. Muse mixes cases — the picker footer says Esc to interrupt, the thinking line says esc to interrupt — so this bites if any rule migrates from contains to regex.

8. One non-issue, verified: ctrl+o expands output inline rather than opening an alternate-screen viewer, so the prompt chrome stays at the bottom and no skip-state viewer rule is needed for it.

Raw captures available for any of these.

[ohk]

@mjdouglas Thanks for the detailed vendor-side captures — cross-checked against strings in the shipped muse-bin binary and folded in as 9da6a45a on this branch (pushed to feat/muse-pick-generic-blocked-2):

Your 3 findings (2026-08-10 17:08):

1. Pick 5→6th line miss — widened pick_request_blocked to bottom_non_empty_lines(8) and added Enter to toggle for multi-select (any OR). Also widens working_esc_interrupt not-gate to same 8 so Esc to interrupt in pick footer doesn't misclassify as working (contains is case-insensitive). Fixes Greptile 5 vs 8.

2. YOLO only --yolo — changed idle_status_fallback from contains YOLO to line_regex '^\s*\S+ · (none|minimal|low|medium|high|xhigh|ultra) · ' (model · effort · cwd shape, · U+00B7). Covers absolute /tmp/... cwds as well; vendor's · [~/] variant also handled (current · is slightly more permissive, same effect).

3. Trust dialog Do you trust this workspace? — added workspace_trust_blocked prio 970 bottom(12) contains "Do you trust..."+ any Trust and continue / Use Up/Down.

4. Idle typed ⟩ <draft> — split idle_prompt into any [{line_regex ^\s*⟩\s*$},{line_regex ^\s*⟩\s+\S}] (multiple top-level line_regex AND, so OR via any as noted).

Your 8 edge cases (20:54):

1. User menus /model enter confirm · esc go back — added menu_request_blocked prio 940 bottom(8) any {enter confirm, esc go back, esc close, space toggle} — generic on footer chrome, blocked by convention.

2. ⟩ picker row vs prompt — kept idle_prompt tight bottom(5) + not on both pick footers + 4 menu anchors; menu's higher prio (940>700) also wins.

3. Typed draft wrapping — second ⟩\s+\S pattern in tight 5-line region, handles ⟩ draft wrapping.

4. blocked_approval prose — narrowed from Do you want.../Allow to footer chrome Allow once/Allow for this session/Always allow in this workspace/Yes, proceed (network approval via Yes, proceed, not title at 10th line).

5. Working Finishing up — kept generic contains esc to interrupt (covers ◇/◆ Running / Finishing up / ◆ Ran command), no spinner-specific regex.

6. Banner transients — no rule keys on Muse Code 0.1.0 / switched model; idle fallback no longer uses YOLO/model literal.

7. Case-sensitivity — notes contains insensitive vs regex not; remained on contains for Esc/esc.

8. ctrl+o inline — verified no alternate-screen viewer, no skip_state_update needed.

Also: lookup_agent now matches muse-bin-<version> digit check (real launcher execs muse-bin-0.1.0-R708.1) to avoid museum/muse-binary false positives, and website/agent-detection/muse.toml mirrored.

Verified: cargo test -- detect 169 passed, scripts/agent_detection_manifest_check.py --require-website ok.

#2588 muse resume <id> left as follow-up per your note.

Raw captures appreciated — happy to adjust if you see more menu verbs.

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4cae02a1-d896-4afc-a3af-164bad20ed45

📥 Commits

Reviewing files that changed from the base of the PR and between 4320fe1 and 9da6a45.

📒 Files selected for processing (3)

• src/detect/manifests/muse.toml
• src/detect/mod.rs
• website/agent-detection/muse.toml

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

• src/detect/mod.rs

[ogulcancelik]

@ohk this is still useful and the implementation review is clean. the vendor captures cover the required idle, working, picker, trust, menu, and approval states, and the final rules keep those controls in bounded bottom regions. please rebase onto current master, add the feature entry to docs/next/CHANGELOG.md, re-check the live state cycle against the current Muse build, and rerun checks and both review bots.

[ohk]

@ogulcancelik done — rebased onto current master, added the changelog entry, and fixed two small things the sync surfaced (stale agent array sizes, missing ui.sound.agents.muse in the config reference). all checks pass and the state cycle looks good against the current muse build. bots are running on the new head.

[ogulcancelik]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

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

[ogulcancelik]

@ohk i've simplified some stuff, could you verify if this branch works with muse before i merge?

[ohk]

@ogulcancelik approved. All changes working. You can merge it. Thanks for simplification.