runs

An agent run groups the spend of one job. A run row appears whenever a budget check, budget confirm, or record arrives carrying a run id — the raw string you chose with --agent-run-id or SOLWYN_AGENT_RUN_ID — or whenever the SDK reports a solwyn.run(...) scope. runs lists those rows, shows one, and stops one.

list and show accept either credential; stop requires a user login with budget-write permission. All three require a project.

runs list

solwyn --project <project_id> runs list [--range 7d|30d|90d|365d] [--from <rfc3339> --to <rfc3339>] \
  [--q <substring>] [--parent <run>] [--sort last_seen_at|total_cost|total_calls] [--limit 1-100] [--cursor <c>] [--all]

$ solwyn --project proj_0123456789abcdef01234567 runs list --range 30d
Field                                           Value
Name                                   checkout-agent
ID               run_1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a
Cost (lifetime)                             12.345678
Denied cost                                  1.250000
Calls                                              42
Velocity flags       rate_acceleration, future_signal
Stopped                                             -
Stoppable                                         yes
window: 2026-08-08T00:00:00Z to 2026-09-07T00:00:00Z

Costs are lifetime totals. The window decides which runs appear; the cost, denied cost, call, and token figures on each are all-time for that run. The effective window prints to stderr, with a second line when your plan's retention clamped it. Velocity flags are the SDK's content-free velocity detector findings. Stoppable is no for auto-grouped runs — calls made outside any run scope, which carry no run id to stop.

With --all, filters and sort persist, rows remain in Core order, and exhausted JSON has next_cursor=null, has_more=false. Repeated cursors, inconsistent continuation, malformed responses or a later-page failure exit nonzero with no partial success stdout.

runs show

solwyn --project <project_id> runs show <run>

<run> is either the storage id (run_ plus 32 hex characters), read directly, or an exact run name, resolved through the list. A name that matches no run exits 5 with agent_run_not_found; a name that matches several exits 1 with ambiguous_agent_run and lists the candidate ids.

$ solwyn --project proj_0123456789abcdef01234567 runs show checkout-agent
Field                                           Value
Name                                   checkout-agent
ID               run_1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a
Project                                 proj_0123456789abcdef01234567
Parent                                              -
Started                          2026-08-01T10:00:00Z
Last seen                        2026-08-07T12:30:00Z
Lifetime cost                               12.345678
Lifetime denied                              1.250000
Calls                                              42
Input tokens                                    12000
Output tokens                                    3400
Velocity flags       rate_acceleration, future_signal
Stopped                                             -
Stopped by                                          -
Stoppable                                         yes

runs stop

Stop a run from outside the process.

solwyn --project <project_id> runs stop <run> [--yes]

$ solwyn --project proj_0123456789abcdef01234567 runs stop checkout-agent --yes
Field                                                Value
Project                                      proj_0123456789abcdef01234567
Run ID                run_1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a
Run name                                    checkout-agent
Stopped at                            2026-08-08T12:00:00Z
Already stopped                                         no
Leases revoked                                           2
Enforcement deadline                  2026-08-08T12:00:30Z
stops future checks and lease renewals; in-flight requests finish; fully effective by 2026-08-08T12:00:30Z

The CLI displays the resolved run and effects on stderr before interactive confirmation or --yes. Without a TTY and without --yes, it exits 2 before HTTP. Decline, EOF or Ctrl-C submits no stop. Inspect the run after an uncertain write before retrying; stopping stays CLI-only.

What a stop does, precisely:

• Every future budget check for that run id is denied with denied_by_period: "run_stopped", regardless of the project's mode. A CLI check that passed the run id sees reason: "run_terminated" and exit 4; the SDK raises RunStoppedError.
• Every active budget lease for the run is revoked. A leased SDK run learns of the stop at its next renewal, which is why Enforcement deadline can be later than Stopped at: it is the moment the last revoked lease would have expired anyway.
• Requests already in flight are never cut off.
• There is no un-stop. A second stop reports Already stopped yes rather than failing. Start a new run id to resume work.

A project key is refused before any request, exit 3, with a hint to log in. A login without budget-write permission gets the API's 403 and exit 3 with a hint to check your role with solwyn whoami. Stopping an auto-grouped run exits 1 with the API's message that it cannot be stopped. Each stop writes an agent_run.stopped audit event. The rate-limit retry is disabled for stop, so a 429 surfaces immediately rather than replaying the mutation.

Related

• Agent runs — the dashboard's Agents tab and its Stop button
• Run control — how the SDK reacts to a stop, and the velocity detector behind the flags
• budget check — how a stopped run's denial looks to an agent
• costs --agent-run — a run's spend broken down by model or day