Troubleshooting

Most problems fall into one of the cases below. Sinatra posts what it's doing back on the ticket (a rolling GitHub comment or Linear activity), so that thread is the first place to look.

The agent didn't pick up my ticket

Sinatra reacts with 👀 the moment it picks work up. No reaction means it never saw a trigger.

On Linear:

• The issue must be assigned to Sinatra, or a comment must @-mention it.
• Your Linear workspace must be connected. Check Connect Linear in workspace settings — it's optional, and nothing fires until it's connected.

On GitHub:

• Add the sinatra label to the issue, or comment from an account with write access to the repo.
• The repo must be enabled in the GitHub App install. Open workspace settings and confirm the repo is selected; you can change the enabled repos at any time. See GitHub App.

No pull request appeared

Open the ticket and check the workstream state (see the table in How it works). The usual reasons:

• Waiting on you. With brainstorm.enabled or planning.enabled set in .sinatrarc, the agent posts a requirements doc or plan and pauses in brainstorm_review / plan_review until you reply to approve or refine it.
• Tests are failing. If you set a hooks.test_command, it must pass before the PR opens. The agent retries, then surfaces the failure on the ticket.
• The run hit a billing limit. The state shows payment_required and Sinatra posts why (see below).
• The run failed. The state shows failed with an explanation on the ticket.

"You're out of free tasks" / payment required

The workstream moves to payment_required and Sinatra posts a message when a run is gated:

• Free tier daily cap. 5 tasks/day on your own key or Codex, 1/day on Sinatra's managed key. It resets at the start of the next calendar day in your workspace's timezone (UTC if unset). Connect your own key for the higher allowance, or upgrade to Monthly to remove the daily cap.
• Managed balance empty. Top up your prepaid balance, or turn on auto-recharge, in workspace settings.
• Subscription inactive. Update billing in workspace settings.

See Billing for how the free tier and metering work. A task counts once per workstream, the moment Sinatra starts work on it — re-running the agent on the same ticket does not consume another.

The PR is stuck as a draft

PRs open as drafts on purpose. Before flipping to ready, the agent reviews its own diff against the ticket. If you comment while it's still reviewing, it holds the PR as a draft and addresses your feedback first, then marks it ready. This is expected — give it a moment, or check the ticket thread for what it's doing.

CI keeps failing and the agent stopped

A CI failure sends the agent back to rework on the same branch. It retries up to ci.max_rework (two by default) in .sinatrarc, then pauses for a human rather than looping forever. Raise ci.max_rework, or fix the branch yourself and comment on the PR to nudge it.

I want it to start over, or stop it

• Start over from scratch. Reply with an unambiguous request like "scrap this and start fresh" — Sinatra does a destructive restart (drops the sandbox, deletes the branch, closes the draft PR) and begins again. Ordinary feedback continues the existing run instead. See Steering a run.
• Stop it. On GitHub, remove the sinatra label or close the issue; reopening a still-labeled issue resumes. On Linear, use the agent session's Stop control or move the issue to Cancelled / Done / Duplicate.

The agent ran the wrong model

• Free managed runs are forced onto openai/gpt-5.4 (opencode), regardless of what .sinatrarc sets. Connect your own key or a Codex subscription to run the model you configured.
• A per-user override may be in effect — a teammate's workspace settings can override the repo's model for the runs they trigger. See per-user overrides.
• No agent.model set? Sinatra picks a default from your connected credentials. See Models.

My .sinatrarc isn't taking effect

• It must live at the root of the target repo and be valid JSON.
• Unknown keys are ignored with a warning, not an error — check for typos against the .sinatrarc reference.
• The engine is fixed for the life of a workstream, and the model must belong to that engine (claude-code uses bare names like opus; opencode uses full slugs). A mismatch fails the run with a clear message. See Models.
• agent.model_provider was removed and is ignored — the provider is derived from the engine and model.

Sinatra didn't merge my PR

It never will — by design. Sinatra only pushes branches and opens pull requests; merging stays with you and your CI.