fix(persona): restore agent-relay MCP injection for spawn-modal personas

[khaliqgant]

Problem

Selecting a persona in the spawn modal launches an agent whose harness has no agent-relay MCP — it can't message, check inbox, or appear properly on the relay.

Root cause

spawnPersonaWithMode passed skipRelayPrompt: true to the broker's spawnPty, on the assumption that the workforce CLI (agentworkforce agent <persona>) would inject the relay MCP itself from the broker env.

But in the broker (relay/crates/broker/src/worker.rs), skip_relay_prompt suppresses both:

1. broker-side MCP arg injection (harmless here — agentworkforce isn't a CLI the broker recognizes, so this is a no-op anyway), and
2. the RELAY_AGENT_NAME / RELAY_AGENT_TOKEN env stamps on the worker process.

The workforce CLI's resolveRelayMcpFromEnv requires RELAY_API_KEY and RELAY_AGENT_NAME; with the name stamp suppressed it silently skips its own injection, so the inner harness launches with no relay MCP at all. (Direct claude/codex spawns work because the broker injects --mcp-config / --config mcp_servers.* for recognized CLIs.)

Fix

• Drop skipRelayPrompt: true from the persona spawn. The broker now stamps RELAY_AGENT_NAME/RELAY_AGENT_TOKEN/RELAY_AGENT_TYPE/RELAY_STRICT_AGENT_NAME on the worker; the wrapper command is unchanged (verified: detect_cli_name('agentworkforce') matches no injection or bypass-flag branch).
• Export AGENT_RELAY_BIN on the broker process (inherited by workers) so the workforce CLI's broker-aware agent-relay-broker mcp-args --register injection resolves the same broker binary Pear runs — a bare PATH lookup fails in packaged installs and can hit a version-skewed global binary in dev. Without it the CLI still works via the legacy @relaycast/mcp fallback, but the pre-registered path is the intended one.

Testing

• vitest run src/main/broker.test.ts — 59/59 pass, including a new regression assertion that persona spawns do not set skipRelayPrompt.
• Full npm test — 109/109 pass.
• tsc -p tsconfig.node.json — no new errors vs HEAD baseline.

Note: requires Pear restart (new broker process env) to take effect; existing running brokers won't have AGENT_RELAY_BIN but the persona env-stamp fix applies on the next spawn through a restarted broker.

🤖 Generated with Claude Code

[codeant-ai]

Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI.

[coderabbitai]

📝 Walkthrough

Walkthrough

The broker's binary resolution and workforce persona spawning are refactored to enable relay MCP injection. The return type of resolveHarnessBrokerBinary() now distinguishes between the potentially-shimmed launch path and the real underlying broker binary, which is then passed to spawned workers via AGENT_RELAY_BIN. Workforce persona launches remove the skipRelayPrompt flag to allow relay MCP injection.

Changes

Broker Relay MCP Injection

Layer / File(s)	Summary
Binary Resolution Refactoring src/main/broker.ts	resolveHarnessBrokerBinary() returns both binaryPath (shimmed, if applicable) and realBinaryPath (always the true broker binary). Instance-name-supported brokers return both equal; legacy --name shim paths return realBinaryPath as the actual binary and binaryPath as the compatibility wrapper.
Spawn Environment & Workforce Persona Relay src/main/broker.ts, src/main/broker.test.ts	Spawned workers receive AGENT_RELAY_BIN env pointing to the real broker binary, bypassing PATH-based lookup issues. Workforce persona PTY spawn requests remove skipRelayPrompt, enabling broker-side relay MCP injection. Test assertions updated to verify the absence of skipRelayPrompt: true in spawn payloads.

Possibly Related PRs

• AgentWorkforce/pear#136: Overlaps in the spawnPersona/sPTY pathway; #136 changes spawn-result normalization while this PR adjusts relay behavior for workforce personas.
• AgentWorkforce/pear#164: Both touch broker startup, resolveHarnessBrokerBinary shimming, and spawn env for persona flows.
• AgentWorkforce/pear#153: Both modify workforce persona launch/spawn behavior and tighten spawnPty argument assertions around persona CLI args.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A shimmer shimmed, a real path shines,
Workers now know which broker's lined,
Relay flows true for workforce souls,
No skippy flags—injection rolls!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	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 accurately summarizes the main change: restoring agent-relay MCP injection for personas spawned from the modal, which is the core fix addressed by removing skipRelayPrompt and exporting AGENT_RELAY_BIN.
Description check	✅ Passed	The description comprehensively explains the problem, root cause, and fix. It clearly relates to the changeset modifications in broker.ts and broker.test.ts, documenting why skipRelayPrompt was removed and AGENT_RELAY_BIN is exported.
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.

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

✨ 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 pear/workforce-e3c9d114

---

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

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[codeant-ai]

Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI.

[khaliqgant]

Full review (high effort: 7 finder angles → 1-vote verify)

No blocking findings. Verified across pear + the relay broker (Rust) + the workforce CLI:

• detect_cli_name on the agentworkforce binary (and the npx/node fallbacks) matches no broker injection or bypass-flag branch — wrapper command is byte-identical with the flag removed.
• mcp-args --register ignores the inherited RELAY_AGENT_TOKEN env (the mutual-exclusion bail only fires on the explicit --agent-token flag, which the workforce CLI never passes); a fresh registered token always wins, and relaycast registration is an upsert — no double-registration conflict.
• AGENT_RELAY_BIN is the ecosystem-standard override (harness-driver broker-path reads BROKER_BINARY_PATH ?? AGENT_RELAY_BIN with an existsSync guard), so workers inheriting it resolve the exact binary serving their workspace; worst case on shape skew is the workforce CLI's documented @relaycast/mcp fallback — degraded but functional, strictly better than the prior PATH lookup.

Applied review cleanup (76c2f2c): resolveHarnessBrokerBinary now returns realBinaryPath explicitly instead of the caller reverse-engineering it from the shim env key.

Non-blocking notes / follow-ups (out of scope for this PR):

1. Pre-existing: spawnPersonaWithMode never applies normalizeCloudSpawnInput, so persona spawns on a cloud-only session were and remain unsupported (persona resolution also runs execFileSync locally). Unchanged by this diff.
2. Deeper fix in the relay repo: worker.rs should stamp RELAY_AGENT_NAME regardless of skip_relay_prompt (matching the existing AGENT_RELAY_RESULT_* always-stamp rationale), and the broker could export its own binary path to workers — that would make this caller-side fix unnecessary and benefit non-Pear clients.
3. The persona startup now includes the workforce CLI's mcp-args subprocess (15s cap) — well inside the 120s persona-readiness budget; intended cost of the injection.

🤖 Generated with Claude Code

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/main/broker.test.ts (1)

867-878: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a regression assertion for broker-start AGENT_RELAY_BIN wiring.

This update guards skipRelayPrompt, but the PR also changes broker-start spawn env contract. Please assert that the spawned broker options include env.AGENT_RELAY_BIN to keep that path regression-covered.

Proposed test addition

   expect(local.spawnPty).not.toHaveBeenCalledWith(expect.objectContaining({
     skipRelayPrompt: true
   }))
+  const brokerSpawnOpts = mock.HarnessDriverClient.spawn.mock.calls.at(-1)?.[0] as {
+    env?: Record<string, string>
+  } | undefined
+  expect(brokerSpawnOpts?.env?.AGENT_RELAY_BIN).toEqual(expect.any(String))

As per coding guidelines **/*.test.{js,ts,tsx}: Add regression tests when touching broker start, event streaming, PTY buffering, spawned personas, or integration notifications. Include duplicate/replay cases, not just the happy path.

🤖 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 `@src/main/broker.test.ts` around lines 867 - 878, Add a regression assertion
ensuring the spawned broker process receives AGENT_RELAY_BIN in its env: add an
expectation alongside the existing spawnPty checks that validates local.spawnPty
was called with an options object containing env: expect.objectContaining({
AGENT_RELAY_BIN: expect.any(String) }) (use expect.objectContaining and
expect.any(String) to avoid coupling to the exact value) so the broker-start
spawn env contract is covered; place this assertion near the other
expect(local.spawnPty)... checks that validate args and skipRelayPrompt.

Source: Coding guidelines

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

Outside diff comments:
In `@src/main/broker.test.ts`:
- Around line 867-878: Add a regression assertion ensuring the spawned broker
process receives AGENT_RELAY_BIN in its env: add an expectation alongside the
existing spawnPty checks that validates local.spawnPty was called with an
options object containing env: expect.objectContaining({ AGENT_RELAY_BIN:
expect.any(String) }) (use expect.objectContaining and expect.any(String) to
avoid coupling to the exact value) so the broker-start spawn env contract is
covered; place this assertion near the other expect(local.spawnPty)... checks
that validate args and skipRelayPrompt.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b5f37cf1-6b68-44ee-85a9-5f7c50ae78bd

📥 Commits

Reviewing files that changed from the base of the PR and between 0a30e1f and 76c2f2c.

📒 Files selected for processing (2)

• src/main/broker.test.ts
• src/main/broker.ts

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

ℹ️ pr-reviewer: review only — no file changes were applied to the PR (nothing to commit after review). The notes below are advisory and were not pushed.

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.

[agent-relay-code]

pr-reviewer could not complete review for #191 in AgentWorkforce/pear.
The review harness exited with code 1.
No review was posted; this needs operator attention.