Troubleshoot setup and agent behavior

Start in the folder where you expect Balladeer to work. Installation, repository connection, loaded tools, current guidance, and CI evidence are separate things; check the one that failed.

My agent stays quiet#

Run balladeer --version and balladeer status in that checkout. Balladeer deliberately stays quiet in a folder with no matching connected repository. It recognizes Git remotes, including a fork's upstream. An unavailable or revoked connection needs its reported repair; it is not an empty catalog.

If installation succeeded, open a fresh host session and confirm Balladeer's native tools are loaded. Ask the agent to read get_promise_setup for this connection's current guidance and capture preference. Capture Off suppresses unsolicited offers, and unavailable policy also suppresses them. Neither prevents an explicit capture request. A quiet session does not by itself prove a malfunction.

If a tool is missing, report the exact client, CLI version, and refusal. A saved MCP entry, hook, or successful server response does not prove the agent received or acted on the guidance.

Setup is waiting or stopped early#

Complete approval in your own browser and repeat the same setup command to resume. Setup's shorter wait from an agent shell does not cancel the saved pairing. Use --choose-workspace only when you intend to select another workspace, rather than to retry an unfinished approval.

Someone else's setup cannot give this laptop a credential. An invited teammate uses setup --existing; an administrator handles missing repository enrollment or CI. Avoid restarting completed repository setup when only this machine needs connecting.

The command is missing or an older release is running#

Use npx -y balladeer@latest install, reopen the terminal or host, and check balladeer --version. If the command is already installed, balladeer update upgrades it. Follow a reported manual PATH step on an unsupported shell. A background update is not proof the current session has restarted.

A local write was refused#

An npm cache error before Balladeer starts is different from a credential-folder refusal. For an npm cache permission error, use an allowed writable temporary npm cache or your host's normal permission process. Do not use sudo, change ownership indiscriminately, or delete credentials.

Keep the private credential store outside the repository. For a configuration conflict or malformed host file, follow the exact reported repair and preserve unrelated settings. A failed optional session-stamp write does not authorize moving credentials or inventing a session ID.

A promise did not appear in planning#

Give the agent the promise ID if you know it. Otherwise ask it to use discover_intent with the intended behavior and paths it expects to touch. Relevant results need a full read before they guide work. Check coverage and truncation; a search miss does not prove no promise exists.

A renamed path can leave promise scope out of date. balladeer status can report missing scope paths from a bounded local check; it does not rewrite agreed scope. Review a needed correction through the normal meaning-revision path. Agents can report an irrelevant discovery lead or a known missed promise with report_promise_context_feedback; that feedback is not an edit or approval.

I agreed, but it is still Unprotected#

Agreement preserves the meaning and makes the promise eligible for agentic checking on push. An agentic kept result does not change the sealed Protected status. For that separate status, a verifier still needs to be built and qualified through CI. Use the promise page's Ask your agent to build the checks instruction or ask your connected agent to continue from the promise ID. A copied instruction, prepared packet, or passing PR is not qualification. See protect your first behavior.

For a failed, missing, or inconclusive check, follow resolve a result. When contacting support, include the bounded error, client and CLI version, affected promise link if relevant, and observed time. Keep credentials, one-time codes, raw logs, and source out of the message.

The push check did not run#

Confirm setup installed the durable command and reported the push check on. In Codex, trust Balladeer’s hooks under /hooks, including newly changed entries. MCP tools being visible does not establish hook execution.

Check that the repository is connected, the laptop-wide check has not been turned off, and a repository-specific entry is not taking precedence. Report mode runs after a successful agent push; a failed push is not checked. Plain terminal pushes need an explicitly installed Git hook.

For an unavailable login, budget exhaustion, unanchored promise, or failed report, read the reason and restore that prerequisite. Do not treat silence or an unfinished check as kept. See agentic code review on push.