running-paid-api-jobs

Running Paid API Jobs

Overview

Paid runs are budget-bound operations, not normal retries. Preserve the user's authorization exactly, prove the run context, capture artifacts, and report spend without exposing secrets.

When to Use

Use this for paid model/API commands, evals, benchmarks, pilots, or scripts where the user gives a cost cap, budget, max-cost flag, or "single approved run" language.

Do not use this for free local tests, CI, dry runs, or mock/offline evals unless they gate a later paid run.

Workflow

1. Lock the authorization

• Identify the exact command, cost cap, run count, cwd, branch, and expected artifact paths.
• If the user supplied an exact command, run that command or the closest shell-equivalent; do not silently change paid parameters.
• Never raise the cap, increase N, broaden conditions, or run another paid attempt without fresh authorization.

1. Preflight without spend

• Verify cwd, branch, SHA, dirty state, and required local dependencies.
• Check that required credentials exist without printing their values.
• Prepare unique output/log paths. Preserve failed-attempt logs instead of overwriting them.
• For runs expected to take more than ~1 hour: require checkpoint/resume support before starting. Confirm the harness writes progress checkpoints and document the exact --resume (or equivalent) invocation in advance — local desktops lose power and restart mid-run. If checkpointing is unavailable, stop and get explicit user acknowledgment of the all-or-nothing risk before spending.
• Propose chunked execution (resumable segments) to the user as part of the authorization for long jobs; never silently restructure an exactly-specified command into segments. Suggest offloading multi-hour runs to a remote or always-on node instead of the interactive desktop when one is available.

1. Run once under capture

• Start a timer and capture stdout, stderr, exit code, and output directory.
• If the run fails before provider/API construction and no spend occurred, report that clearly before deciding whether any local equivalent is allowed.
• If the paid call starts, treat the run as spent even if it fails later.