Safety, limits and feedback

Budget protection

Set limits on quota, cost or tokens for one agent terminal, and choose what Orkestra does when a limit is reached.

On this page

Purpose

An agent uses quota, money and tokens while it works. Budget protection watches the readings of one terminal. You set a limit for each reading. When a reading reaches its limit, Orkestra acts for that terminal. It sends a message to the agent, or it stops the terminal. Use it to keep an agent that runs alone inside a plan limit.

Budget protection reacts to a reading. It is not a billing cap, and a reading can come late. It is off for every terminal until you turn it on.

Where to find it

Budget protection is a section of the Terminal info menu of a terminal. It is below the Your note block and above the buttons Name, Recap and Sleep. Open the menu with the round i button on the title bar of the terminal, or right-click a terminal row in the Agents panel. See The terminal info menu. Each terminal has its own limits.

Budget notices show at the bottom right of the window. A terminal that budget protection stopped shows its state inside its own window.

What you see

Header (always shown)

  • Budget protection — the section title, with a shield icon.
  • Budget protection switch — turns protection on or off for this terminal. It is not shown for an agent without budget support, or before Orkestra knows the account of the agent. It is grey while an action runs and while protection cannot start yet.

Banners (shown when they apply, also while protection is off)

  • Outcome banner — a green banner with a check mark, or an amber banner with a warning triangle. It tells how the last action ended.
  • Status banner — an amber banner (a problem), a red card titled Disabled for this harness, or a blue banner with a spinning icon (an action runs now).

Body (shown while protection is on)

  • Account, Billing and Plan — who pays for the agent. Account shows an e-mail, an organisation name, "API key", "Env token · <host>", "Account" with 8 characters (Codex) or "Identified". Billing shows "Subscription", "Metered API key" or "Unknown". Plan shows only when the plan is known.
  • Compatibility: … — a line with an arrow. The word after the colon is Passed, Failed, Pending evidence, Checking or Not checked. Click it to open the detail, the agent version with the check time, and the Recheck compatibility button.
  • Measurement rows — one line for each reading. From left to right: a checkbox (name "<row name> threshold", for example "Weekly quota threshold"), the row name, the current value, then ≥ and a threshold field with its unit.
    • Row names: account quota windows named by length, for example 5-hour quota and Weekly quota (unit %); Session cost (unit dollars, an estimate); Thread tokens (unit millions of tokens).
    • The value shows as "83 %", "$1.24" or "1.2M". It shows "—" when there is no value.
    • The threshold field shows "%" after a quota, "$" before a cost and "M" after a token count. The first default limits are 80 %, $5 and 1 M (one million tokens).
    • Markers next to the value: ≈ (tooltip "Estimate: computed by the harness from token usage, not a bill"); a round alert icon (tooltip "Stale: the last known value; it cannot trigger until a fresh reading arrives"); a clock icon (tooltip "Startup reading, not live: it cannot trigger until a fresh reading arrives while this terminal runs").
    • A line under a row can show an error, or "Already … — raise the value, then check it."
  • Unavailable rows — grey lines in the form "<name> — <reason>". They name a reading that is not available, and why.
  • Age line — small grey text, for example "Updated 12 s ago".
  • When a threshold is reached — a menu with three actions:
    • Interrupt, then send message — Orkestra presses Esc in the agent, types your message, waits about 2 seconds, then presses Enter.
    • Send message (no interrupt) — Orkestra types your message, waits about 2 seconds, then presses Enter. This is the first choice for a new terminal.
    • Force sleep — Orkestra stops the process of the terminal, also while the agent works. The terminal goes to sleep.
  • Message — a text box for the message that the two message actions send. It holds up to 4,000 characters. The first text is "Pause and tell me what you were doing." It is hidden when the action is Force sleep.
  • Hint line — one short sentence in grey. See "States and messages".

Budget notices

  • A notice card with a warning triangle, a title, a second line and a close button (name and tooltip "Dismiss").

In the terminal window

How to

Turn on budget protection for a terminal

Before you start, the terminal runs Codex or Claude Code, and the Budget protection switch is not grey.

  1. Click the Terminal info button (the round i icon) on the title bar of the terminal.
  2. Click the Budget protection switch.

Result: the section opens and the switch is on. Orkestra checks one measurement for you, the first live one that is not over its limit, with the default limit. For a new terminal the action is Send message (no interrupt). To turn protection on again after an action ran, do the same steps.

Change a limit

Before you start, turn protection on.

  1. Click the Terminal info button on the title bar of the terminal.
  2. Click the threshold field of a measurement row (right of ≥).
  3. Type the new number in the unit of the row: percent, dollars or millions of tokens.
  4. Press Enter.

Result: Orkestra saves the limit. Leaving the field or closing the menu also saves it. If the text is not a number, the row shows "Enter a non-negative number with the displayed unit." If the new limit is at or below the current value, the action can run at once.

Choose which measurements to watch

Before you start, turn protection on.

  1. Click the Terminal info button on the title bar of the terminal.
  2. Click the checkbox of a measurement row.

Result: a checked row is watched. An unchecked row only shows its value. Orkestra checks the latest value at once, so a checked row that is over its limit can run the action.

Choose what happens at a limit

Before you start, turn protection on.

  1. Click the Terminal info button on the title bar of the terminal.
  2. Click the When a threshold is reached menu.
  3. Choose Interrupt, then send message, Send message (no interrupt) or Force sleep.

Result: Orkestra saves the action. The Message box shows for the two message actions.

Change the message

Before you start, turn protection on and choose a message action.

  1. Click the Terminal info button on the title bar of the terminal.
  2. Click the Message box.
  3. Type the new text.
  4. Click outside the box.

Result: Orkestra saves the text when you leave the box. An empty box is refused while a message action is on: the box shows the saved text again and says "A message is required while this action is armed. The saved message was kept."

Turn on protection when a limit is already reached

Before you start, turn protection off. Every measurement is already at or over its default limit.

  1. Click the Terminal info button on the title bar of the terminal.
  2. Click the Budget protection switch. The section opens and the switch stays off.
  3. Click the threshold field of a row that says "Already … — raise the value, then check it."
  4. Type a number that is higher than the current value.
  5. Press Enter.
  6. Click the checkbox of the same row.
  7. Click the Budget protection switch again.

Result: protection is on. A row that is still over its limit stays unchecked.

Turn off budget protection

  1. Click the Terminal info button on the title bar of the terminal.
  2. Click the Budget protection switch.

Result: the body closes. Orkestra keeps your limits, your checks, the action and the message for the next time. The switch is grey while an action runs. You cannot turn it off then.

Recheck compatibility

Before you start, protection is on, or the red Disabled for this harness card shows. On the red card, skip step 2.

  1. Click the Terminal info button on the title bar of the terminal.
  2. Click the Compatibility: … line.
  3. Click Recheck compatibility.

Result: the section says "Checking compatibility…" and then shows the answer. See "States and messages".

Dismiss a budget notice

  1. Find the notice at the bottom right of the window.
  2. Click the Dismiss button (the X icon).

Result: the notice closes. The same notice does not show again.

States and messages

Line under the header while protection is off

  • "Budget monitoring is not supported for this harness." — the agent is not Codex or Claude Code, or the terminal has no agent. There is no switch. A terminal without an agent keeps this line when you put it to sleep.
  • "Budget identity is not identified." — Orkestra does not know the account yet. Other texts can replace it, for example "Budget identity is read when this terminal starts.", "Claude Code reports no logged-in account for this terminal." and "A Codex API key is present, but API-key usage is not measured; live quota requires a verified ChatGPT account." There is no switch.
  • "Terminal is dormant. Settings are retained; protection resumes only after its identity is revalidated." — the terminal does not run. A Codex or Claude Code terminal shows it, for example when it sleeps. A terminal without an agent shows the "not supported" line above instead.
  • "Waiting for a fresh live budget reading." — the switch is grey until a usable reading arrives.
  • "Add a message before turning protection on." — the message is empty. The switch works: it opens the Message box and says "Add a message, then turn on."
  • "Off. Turn on to set thresholds for this terminal." — shows only in a section that you opened as in "Turn on protection when a limit is already reached".

Hint line while protection is on

  • "Reacts after a reported reading reaches a threshold — not a billing cap."
  • "Awaiting next window." — a watched quota window ended. Orkestra waits for a reading of the next window.
  • "Waiting for live budget data." — no reading yet.

Status banners

  • Amber, a reading is missing for the first times: "Weekly quota not received. Retrieval failed 1 of 3 — next attempt in 0:42. After 3 failures this terminal is put to sleep." The age line then reads, for example, "Updated 2 min ago · Weekly quota 10 min ago".
  • Amber, Orkestra cannot read the usage now (it is busy or not reachable): "Weekly quota not received — rate-limited, retrying. Next attempt in 0:42. An idle terminal is not put to sleep." The reason can also read "server error", "network error" or "timed out". When the terminal works without the reading, the text ends with "This terminal is working without it, so failed attempts now count (1 of 3)."
  • Amber, the saved account does not fit: "The saved account and billing settings no longer match this terminal." Other texts: "The configured budget identity no longer matches this terminal.", "Budget protection has an incomplete saved trigger. Disable and enable it again to restore monitoring." and "The login stored for this terminal changed, so the account usage it reports no longer describes this terminal."
  • Amber, no first report yet: "Waiting for the first budget report." Other texts: "Waiting for the harness to report a fresh live measurement." and "Live Codex quota starts after this session's first turn."
  • Red card Disabled for this harness — Orkestra cannot verify the usage format of the agent. The card shows the reason, the agent name with its version ("version not checked" when unknown), and Recheck compatibility. Protection is locked.
  • Blue, an action runs: "5-hour quota 83 % ≥ 80 % — sending message…". The end can also read "confirming delivery…", "waiting to submit…" or "stopping…". The switch, the checkboxes, the fields, the menu and the Message box are grey.

Outcome banners

  • Green: "Message delivered · 5-hour quota 83 % · 14:32".
  • Green: "Stopped · 5-hour quota 83 % · 14:32". After 3 failed readings: "Stopped · Could not retrieve Weekly quota after 3 attempts (rate-limited, HTTP 429). · 14:32". After a compatibility failure: "Stopped · 14:32".
  • Amber: "Message sent, but no new copy found in the session transcript or on screen — delivery unconfirmed · 14:32".
  • Amber: "Message was not sent · Multi-line text needs bracketed paste in this terminal. · 14:32". Other details: "The terminal declined the guarded input.", "The interrupt key was not accepted." and "The terminal input could not be sent."
  • Amber: "Stop could not be confirmed · … · 14:32".
  • Amber, after a restart: "Message delivery unconfirmed · The protection action was interrupted by an app restart, so its outcome could not be confirmed. · 14:32".
  • The time is the 24-hour time of the action. The banner stays until you turn protection on again.

Measurement rows

  • "Enter a non-negative number with the displayed unit." — the limit text is not valid.
  • "This measurement could not be added. Re-enable protection to include it." — turn protection off and on again.
  • "Already 83 % ≥ 80 % — raise the value, then check it." — an unchecked row is already over its limit.
  • Unavailable rows, for example: "Cost — not reported by Codex"; "Cumulative tokens — not reported by Claude Code"; "Thread tokens — Live Codex quota starts after this session's first turn."; "Thread tokens — Live Codex quota attribution is not available on this platform."; "Weekly quota — rate-limited, HTTP 429; waiting for the harness's next report"; "<name> — not measured yet; it cannot trigger until a reading arrives"; "Account readings — cannot be matched to this login; quota actions use this terminal's own reports only".

Recheck answers

  • "Checking compatibility…" — the check runs.
  • "Compatibility recheck Passed (2.1.287)." — the result, with the agent version and a reason when there is one. The word can also be Failed or Pending evidence.
  • "Compatibility recheck finished. This terminal’s current verdict is passed (2.1.287): …" — no check attempt of this terminal is on record, so the text shows its current verdict.
  • "Compatibility recheck could not run. Try again after launching this harness once." — start the agent in this terminal once, then try again.
  • "Compatibility recheck finished, but this terminal is no longer available." — the terminal is closed.

Budget notices (bottom right)

  • "Budget protection is not measuring" — second line: "<terminal name> cannot read Weekly quota: rate-limited since 14:20. Protection keeps retrying and does not stop an idle terminal." It shows after 5 minutes without a reading. The second line names every measurement that cannot be read.
  • "Budget follow-up" — second line: "<terminal name> is still working 2 minutes after the budget message." It shows when the agent still works 2 minutes after a message action.
  • Orkestra also sends both notices to Telegram when remote control is on and a phone is paired. See Remote control with Telegram. It sends no system notification and no sound for them.

A terminal that budget protection stopped

  • The window shows Sleeping, with "Stopped by budget protection." in the help text. The agent session is kept. Orkestra shows no pop-up for this stop.
  • To bring the terminal back, click its saved text (or Wake). The agent resumes its saved session. See Terminal states, reconnect and history.
  • A wake does not turn protection on again. The outcome banner stays until you turn it on.
  • After a restart of Orkestra, the terminal comes back as Session not live. Its limits and its outcome banner stay. See the line "Terminal is dormant." above.
  • If the process may not have ended, Orkestra shows the message "Process was signalled, but its exit could not be proven. Reload to reconnect." Use Reload on the terminal.

Limits and tips

  • Only Codex and Claude Code have budget protection. Cursor, OpenCode, Antigravity and plain terminals show "Budget monitoring is not supported for this harness."
  • Codex needs a ChatGPT login. Claude Code works with a Claude subscription login, an approved API key or an environment token. Other setups, such as Claude Code through Amazon Bedrock, Google Vertex or another provider, are not measured. The section then says why.
  • A reading can trigger an action only when it is fresh and live. A stale value, or a startup value, cannot trigger until a fresh reading arrives while the terminal runs.
  • Quota rows come from the usage of your account. Orkestra reads it about every three minutes while a protected terminal needs it. It is the same data as the status bar gauges. See Usage limits. The agent does not have to work: an idle protected terminal reacts too.
  • One account reading can act on many terminals at once. Each terminal runs its own action. Cost and token rows come only from the terminal itself. A terminal with an API key or an environment token gets no account readings from Orkestra.
  • If the login of the account changes while protection is on, a status banner says so and Orkestra does not act on the new readings. Logging back in to the old account recovers it.
  • After 3 failed attempts to read a watched measurement, Orkestra stops the terminal, whatever action you chose. The attempts are one minute apart. While Orkestra cannot reach the usage, it does not stop an idle terminal. It counts the attempts only when the terminal works without the reading.
  • Orkestra also stops a protected terminal when the compatibility check of its agent fails.
  • When you change a limit or check a row while protection is on, Orkestra checks the latest reading once. It can act at once.
  • A message action types into the agent and starts a new turn, also when the agent is idle. A message with several lines needs bracketed paste in the terminal. Without it, the banner says the message was not sent.
  • Orkestra confirms a delivered message by finding it again in the session text or on the screen within 2 minutes. If it finds none, the banner says "delivery unconfirmed".
  • The action runs once for each time you turn protection on. Notices are not saved. Orkestra keeps at most 50 in the stack.
  • A compatibility recheck can fail to run until the agent has started once in this terminal.
  • Tour. The Terminal budget protection tour points at this section step by step. It shows information only: it does not turn protection on, change a limit or the action, or send a message. Start it with Show me on the Protect a terminal’s budget item of the Getting started checklist, or in Settings, System check, Tours. See First-run setup, Getting started and tours.