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

On GitHub, Sinatra reacts with 👀 the moment it picks work up, so no reaction means it never saw a trigger. On Linear it posts a Received task, starting work… activity on the agent session instead.

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 — sinatraai on the hosted app, named after the GitHub App. The name must match exactly, so pick the label Sinatra provisioned rather than creating one by hand; a label you typed yourself is ignored silently.
• A comment alone will not start a run on GitHub. Comments only steer a run the label already started, and only from the repo owner or an organization member.
• 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. The brainstorm and planning phases are on by default, so the agent posts a requirements doc or plan and pauses in brainstorm_review / plan_review until you reply to approve or refine it. Opt out per repo with brainstorm.enabled: false / planning.enabled: false in .sinatrarc.
• 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.

Failing tests are not a cause — see below.

The PR opened but the tests are red

A failing hooks.test_command does not hold the PR back. Sinatra re-runs the agent to fix the failure up to twice; if the tests still fail it opens the PR anyway, notes the failure on the ticket, and leaves the diff for you to judge. Check the ticket thread for the last test output.

"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 below the $2 admission floor (including negative after a long run). Top up to at least $2, or turn on auto-recharge, in workspace settings. An already-running phase is not killed mid-flight; new tasks and later iterations stay parked until the floor is restored.
• Payment past due. A past-due subscription keeps working for a 7-day grace period, then runs are blocked until billing is fixed. Update billing in workspace settings. A cancelled subscription is different: it drops the workspace back to the free tier's daily cap rather than blocking it.

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-codex/gpt-5.6-terra (oh-my-pi, high effort), 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 top-level keys are ignored with a warning, not an error. A typo inside a section (agent, hooks, sandbox, ci, planning) is dropped silently, and a typo inside brainstorm fails the parse — check 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 and oh-my-pi use 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.