[matt2e]

Problem

When a provider refuses an agent's key or sign-in, the turn's reply in the thread gave the owner no route to the fix:

• Codex posted OpenAI's raw error: Codex could not finish: unexpected status 401 Unauthorized: Missing bearer or basic authentication in header, url: https://api.openai.com/v1/responses.
• Goose posted the ACP error bare: ⚠️ I couldn't finish that: Authentication required, or Internal error: Error getting agent reply: Configuration value not found: ANTHROPIC_API_KEY.
• Claude already replied with a sentence linking its section of Settings → Agent setup, but that sentence replaced Claude's own words, which then survived only on the Activity tab.

The owner had to know that the fix lives under Settings → Agent setup → that provider.

Change

All three now reply the same way: a sentence with a Settings link to that provider's dialog, then, on lines of their own, what the provider said, quoted and attributed:

<sentence with Settings link>

<Provider> said:
> <quoted provider text>

The link is buzz://settings?section=agents&provider=<type key> (buzz.codex%2Fcodex, buzz.goose%2Fgoose, buzz.claude-code%2Fclaude-code). It parses to {kind: "settings", section: "agents", provider} and Agent setup opens the dialog whose type key matches, the path Claude's link already took.

An error none of them recognises posts byte-for-byte as before. So does Buzz's own refusal to start Claude without a key, which has no provider words to quote.

Before → after

The after column shows the sentence. Each reply then continues with a blank line, Codex said: / goose said: / Claude said:, and the provider's words quoted. For Codex the quote is the message without the Codex could not finish: wrapper and its trailing period; for Goose and Claude it is the error as reported (sliced to 500 characters, as those reports already did).

Provider	Case	Before	After (sentence; quote follows)
Codex	signed out (Missing bearer or basic authentication)	Codex could not finish: unexpected status 401 Unauthorized: Missing bearer or basic authentication in header, url: https://api.openai.com/v1/responses.	Codex isn't signed in. Head to Settings to sign in.
Codex	refused API key (Incorrect API key provided) or any of the binary's six … could not be refreshed[…]. Please [log out and ]sign in again. messages	Codex could not finish: Your authentication session could not be refreshed automatically. Please log out and sign in again..	OpenAI rejected Codex's sign-in. It may have expired or been revoked. Head to Settings to sign in again.
Goose	missing key (Configuration value not found: <NAME>API_KEY)	⚠️ I couldn't finish that: Internal error: Error getting agent reply: Configuration value not found: ANTHROPIC_API_KEY	⚠️ I couldn't finish that: Goose is missing an API key (ANTHROPIC_API_KEY). Head to Settings to add it.
Goose	refused key or sign-in (Authentication required at the start or after : )	⚠️ I couldn't finish that: goose could not start: Authentication required	⚠️ I couldn't finish that: Goose's provider rejected its API key or sign-in. Head to Settings to check its provider.
Claude	refused key	⚠️ I couldn't finish that: Anthropic rejected Claude's API key. It may have been revoked or run out of credit. Head to **Settings** to replace it.	the same sentence, now followed by Claude said: and > Invalid API key · Fix external API key
Claude	missing key (Buzz refused to start Claude)	⚠️ I couldn't finish that: Claude is missing an API key. Head to **Settings** to add one.	unchanged: the sentence alone
any	other failure	e.g. Codex could not finish: model busy., Codex could not finish: MCP OAuth refresh token was rejected; reauthorization required., ⚠️ I couldn't finish that: Error: overloaded	unchanged

Design

• Each plugin recognises its own error shapes in its setup module, as claude-code/auth.tsx already does: codex/setup.ts explainTurn (sign-in) and goose/setup.ts explainTurn (provider keys). Nothing moves into the Agents service.
• Shared formatter: src/features/agents/failure-words.ts withProviderWords(explanation, who, words) trims the provider's words, quotes at most 500 characters (ending a cut with …), quotes every line, and returns <explanation>\n\n<who> said:\n> …. With no words it returns the sentence alone. The explanation itself is not capped.
• Codex applies the hook inside publish, which every thread notice goes through, so no call site changes. Draft fix(codex): tell every steered thread when a turn fails #2959 replaces the "could not finish" publish with notify(reason), which calls this.publish, so its notices are explained and quoted with no change to its lines. A sign-in Codex refuses at thread/start or turn/start lands in execute()'s catch and is covered. The Activity tab's status keeps Codex's own notice.
• Goose applies the hook in report(), as Claude does.
• Claude keeps its explainTurn sentences; claude-code/index.ts quotes Claude after whatever it explains, except when refusedByBuzz (Buzz's own NO_KEY refusal) produced the error. fix(claude): sign in with a Claude account as well as an API key #2995 adds a signed-out branch inside explainTurn, so this change stays out of that method and merges cleanly with it (verified with git merge-tree).
• Codex's refresh match /could not be refreshed\b[^.\n]*\. Please (?:log out and )?sign in again/i stays within one sentence and the next, so configured values could not be refreshed: enterprise IdP session has no OIDC ID token; sign in again. and the MCP OAuth refresh errors stay raw.
• Remote execution runtimes keep their pass-through explain, as Claude's do; their credentials live on the target.
• No style change. In the thread, paragraphs and blockquotes have --space-4 (16 px) margins that collapse, so the label sits 16 px below the sentence and the quote's bar 16 px below the label (first quoted line 18 px, after the bar's padding). Tightening it would be a thread-wide rule for every paragraph that runs into a quote, so this PR leaves Messages.module.css alone.

Testing

Tests added in failure-words.test.ts, codex/runtime.test.ts (through the plugin's apply, and with the fake app-server refusing thread/start / turn/start), codex/setup.test.ts, goose/runtime.test.ts, goose/setup.test.ts, goose/index.test.ts and claude-code/index.test.ts. They cover each matched shape, the 500-character cut, multi-line quoting, and guards that the unmatched errors above (model busy, both MCP OAuth messages, the two configured values could not be refreshed forms, Error: overloaded) post exactly as before.

Base: 7444eb1299 (origin/main when branched).

Check	Result
New tests, production files at 7444eb1299	18 fail; the other-error guards pass
New tests, production files at the Settings-link-only version of this change	16 fail (every quote); guards pass
New tests, helper with a single newline before X said:	19 fail (every quote)
Replies rendered through MessageMarkdown (throwaway)	<p> sentence + link, <p> "X said:", then <blockquote>; line breaks kept inside it
Thread spacing, headless Chromium with the real tokens and Messages.module.css	sentence → label 16 px; label → quote bar 16 px, → its first line 18 px
failure-words, codex runtime/setup/index, goose runtime/index/setup, claude-code auth/index/runtime/setup, navigation buzz-links test files	12 files, 629 tests pass
bin/pnpm exec tsc --noEmit	clean
biome check --error-on-warnings on changed files	clean
git diff --check	clean
git merge-tree with #2959, #2960, #2995, #2951, #2961, #2944, #2938, #2859	clean, as with 7444eb1299
git merge-tree with #2995	clean; claude-code/index.ts and auth.tsx keep both #2995's signed-out branch and refusedByBuzz; biome clean on the merged files
git merge-tree with #2921	same 22 conflicting files as 7444eb1299 already has with it; its hunks in claude-code/index.ts and goose/runtime(.test).ts byte-identical, so none added

The error text came from the real binaries on a workstation (codex-cli 0.166.0, goose 1.57.0) pointed at a local server returning OpenAI's and Anthropic's 401 bodies, not from OpenAI or Anthropic themselves.

In-app check

This is a browser-build fallback recording, not the desktop app. The recording workstation had no relay to connect to (no .env.local, no local relay), no display server or WebKitGTK, and native identity there needs a real community sign-in; posting from a debug identity into a real community would send messages to an outside service. The fixture stands in for the two agents and the turn: on a mention it posts the reply that each build's own codex/setup.ts / goose/setup.ts explainTurn composes from the raw error strings captured from the real binaries. Real in the recording: each worktree's Buzz frontend, the Playwright fixture relay and production broker, the Agents service delivering the mention, MessageMarkdown with the real Messages.module.css, buzz:// link routing, and Settings → Agent setup with the real Codex and Goose plugins bridged to the real binaries. Spacing measured in the real thread matched the headless numbers above (16 / 16 / 18 px).

Left is BEFORE = origin/main 7444eb1299; right is AFTER = 13b8178396. Both halves run the same script; only the right half then follows the Settings links.

p3-codex-goose-settings-link-before-after.mp4

BEFORE (7444eb1299)	AFTER (13b8178396)

AFTER (13b8178396), close-up of the thread column: sentence, 16 px gap, "X said:", 16 px gap, then the quote's bar.

AFTER (13b8178396): clicking Codex's Settings link opens Settings → Agent setup with the Codex dialog.

Overlap

• fix(codex): tell every steered thread when a turn fails #2959 (draft): its notify(reason) calls this.publish, so its notices are quoted with no change to its lines. This PR edits neither that hunk nor fix(codex): keep a running turn's results in its thread when another thread steers it #2951's.
• fix(claude): sign in with a Claude account as well as an API key #2995: edits Claude's explainTurn, its doc comment, the NO_KEY lines and claude-code/index.ts's imports and setup. This PR leaves those lines alone and adds refusedByBuzz after the ClaudeAuth class.
• Forward goose agent turns through the agent gateway, behind a flag #2921: already conflicts with main in 22 files; this PR adds no new conflict (its hunks in the shared files are byte-identical).

Follow-ups (not in this PR)

• The rendered gap above and below "X said:" is 16 px each because paragraph and blockquote margins collapse. Tightening the paragraph-into-quote gap is a thread-wide CSS change.
• The Codex Settings dialog's framing ("Security reviews need a ChatGPT sign-in made in Buzz") is a separate copy fix.
• Goose's bundled hf-hub prints the same "Authentication required" words, so a Hugging Face refusal would get the provider sentence too. The sentence says "check its provider" rather than naming a key, which still fits, but it is worth a look.
• Goose's Error: Authentication required shape is tested only through explainTurn: SessionControls swallows a control action's error, so no runtime path delivers it today.
• A Goose agent whose provider override differs from goose's default has no way in Buzz to repair that provider's key alone: the Goose dialog's only save action writes device defaults (provider and model) and reconfigures every inheriting agent. The Settings link therefore opens the dialog on the default provider, and the sentence says "check its provider" without naming one. A credentials-only save for a non-default provider is its own change. (A commit that named the provider and preselected it in the dialog was tried on this branch and reverted after review, for this reason.)
• No docs change: docs/buzz-help.md and docs/agents.md do not describe failure replies for any harness.
• Not run in the native desktop app; human check pending.

🤖 Generated with Claude Code

[wesbillman]

🤖 Star Lord’s automated source review via Wes’s account, with independent Rocket, Mantis and Groot coverage.

Three P2 findings: two inline, plus the Settings dismissal defect below.

[P2] Strip item from both outer Settings dismissal identities — src/app/navigation.ts:498–518. leaveSettings() removes provider but keeps the new item in both destructurings. targetKey() reparses the resulting target, so the new requirement that item needs provider throws. Open an item-bearing Goose link while Goose is disabled/unavailable and Close Settings fails immediately; alternatively, return with Back to a plain Settings visit and Close fails when the dismissal predicate reaches the retained item-bearing visit. The browser history driver evaluates all known entries before recording any dismissal, so the exception leaves Settings open. Strip item alongside provider in both places and cover Close directly from an unavailable item target and Close after Back, including Forward skipping the retired visit.

Reviewed head eb81fe497864ba4c94c5c7e1f01ed11f69b8fa01; target base 58116b826171d190a7376fc57b0509c32c507dde; merge base 7444eb12992a237eec786f5b81b94cdf48ff9c65.

Source analysis only: no tests, builds, app execution or code changes. The PR description and all seven screenshots were inspected; the two videos were not inspected. Native recovery, keyboard/focus and screen-reader behavior remain unexercised. One CI snapshot showed Rust/tool integration and CI required failing, two WebKit journey jobs cancelled and Windows skipped; those results were not diagnosed or attributed to this change. This is a COMMENT review, not approval.

[wesbillman]

🤖 Star Lord’s automated source follow-up via Wes’s account, with independent Rocket, Mantis and Groot coverage.

No new actionable findings in this bounded follow-up. Removing the provider-specific commit retires the three P2s from review 5827012733:

• The failure link no longer preselects an override provider in the device-defaults form.
• Settings targets no longer carry item, removing the item-only dismissal key that made Close throw.
• Goose reports generic provider guidance without reading mutable provider identity at failure completion.

The Codex/Claude hooks and shared quoting helper are unchanged from the reviewed revision. Goose retains its generic Settings link and quoted error. As the updated description notes, credentials-only repair for a non-default Goose provider remains outside this change; removing preselection does not implement that capability.

Reviewed head 13b8178396b3c084caff3cb53775b5892c888023, target base 3a1eb5601e997811009d01601786df8af9393a7f, merge base 7444eb12992a237eec786f5b81b94cdf48ff9c65; compared directly with previously reviewed eb81fe497864ba4c94c5c7e1f01ed11f69b8fa01.

Source-only: no tests, builds, apps or code changes. The current description and four screenshots were inspected (the images are byte-identical to the previously inspected copies); one video remains uninspected. Native behavior, keyboard/focus and screen-reader behavior remain unexercised. The single CI snapshot contains running jobs and recorded failures, so it does not establish a green gate; failures were not diagnosed or attributed to this change. This COMMENT is not approval.

[kazemek21]

🤖 Kyle reviewed this PR and the Nexus review-tracker notes and approved with no comments.

Posted by Codex (gpt-6.1-sol) on behalf of kylez.