Metadata-Version: 2.5
Name: open-agent-guide
Version: 0.7.0
Summary: Open Agent Guide submission client and CLI
Project-URL: Documentation, https://www.openagentguide.com/developers/
Project-URL: Homepage, https://www.openagentguide.com
Author-email: "Goshawk Solutions, LLC" <support@openagentguide.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: httpx<0.29,>=0.28.1
Requires-Dist: typer<1,>=0.20
Description-Content-Type: text/markdown

# Open Agent Guide client

Open Agent Guide is a verifiable directory of AI products. It records each
product's capabilities, pricing, compliance, and agent-facing affordances, such
as APIs, SDKs, MCP servers, and CLIs. It grades each product on an AI-native
score.

`oag` is the command-line client for
[Open Agent Guide](https://www.openagentguide.com). Use it for two tasks:

- **Read the catalog.** Search products, read one product with its related
  records, and page through results. Catalog reads are public, so you need no
  account and no token. This is what most people use the client for.
- **Submit catalog proposals.** Validate a batch, submit it, and watch each
  proposal to a terminal state. Submission needs a bearer token.

The `open-agent-guide` package also ships `oag_client`, a typed Python library
that runs the same read and submission workflows from your own code.

- Distribution `open-agent-guide` on PyPI. Import `oag_client`. CLI `oag`.
- Documentation: <https://www.openagentguide.com/developers/>
- MIT licensed.

## Install

The client supports macOS and Linux on Python 3.12, 3.13, or 3.14.

```sh
pip install open-agent-guide        # library + oag CLI
uv tool install open-agent-guide    # isolated CLI install
```

To upgrade, run `pip install --upgrade open-agent-guide` or
`uv tool upgrade open-agent-guide`. To use the library in a project, run
`uv add open-agent-guide`. The client does not support Windows yet. The client
does not support standalone executables yet.

## Tutorial: read the catalog

This tutorial shows a first read from start to end. Catalog reads are public, so
you need no token.

List products. The client prints the server body as JSON.

```sh
oag products list
```

The response holds a `count`, a `results` array, and a `next` link. Read one
product by its slug or its UUID.

```sh
oag products get <slug>
```

Search products by text.

```sh
oag products list --search "code review"
```

Expand related records in the same read. Name the relations you want.

```sh
oag products get <slug> --expand mcp_servers,api_specs
```

Read every page in one array. The client follows each `next` link for you.

```sh
oag products list --all
```

`OAG_BASE_URL` sets the API origin. It defaults to
`https://www.openagentguide.com`. Point it at a staging origin to test.
`OAG_BASE_URL` cannot contain credentials. It cannot contain a path, a query, or
a fragment. The client does not follow redirects.

## How-to guides

### Search and filter products

Combine filters with `--search` and with each other.

```sh
oag products list --has-mcp --tier A
oag products list --category code-generation
oag products list --organization anthropic
```

Pass any other server filter with `--filter KEY=VALUE`. Repeat the option for
more filters.

```sh
oag products list --filter open_source=true --filter has_cli=true
```

List every filter the command accepts with `oag products filters`. The server
rejects an unknown filter with a 400 that names the bad key.

```sh
oag products filters
oag products filters --output json
```

### Read one product with its related records

Request related records with `--expand`. Select a subset of top-level fields
with `--fields`.

```sh
oag products get <slug> --expand organization,capabilities,api_specs
oag products get <slug> --fields name,ai_native_score,ai_native_tier
```

### Page through a large result set

Set the page size with `--page-size`. Read every page in one JSON array with
`--all`; the client follows each `next` link for you.

```sh
oag products list --page-size 50
oag products list --all
```

The server bounds page sizes. The response reports `page_size_default` and
`page_size_max`.

### Submit a batch and watch it

Submission needs a bearer token. Generate a token in your account settings and
export it.

```sh
export OAG_TOKEN=...
```

1. Validate the batch: `oag validate batch.json --output json`. Validation calls
   the server and reports its field-path errors.
2. Submit the batch with a journal:
   `oag submit batch.json --journal batch.journal.json --output json`. The
   journal lets you resume the batch and reconcile it later.
3. Watch the submissions with a journal and a timeout:
   `oag watch --file ids.txt --journal watch.journal.json --timeout 900 --output jsonl`.
   The client polls each unresolved submission until it reaches a terminal
   state.

Use one pacing directory for concurrent validate, submit, and watch commands.
Bearer tokens never appear in transport diagnostics. Catalog proposals are
immutable once created.

### Explain a rejection

Run `status` or `watch` with `--output explain` to read why a submission needs
work.

```sh
oag status 00000000-0000-0000-0000-000000000001 --output explain
```

`--output explain` (`-o explain`) drops the full record dump. It prints a
compact, line-based explanation of each result:

- the lifecycle state, the next-action guidance, the terminal resolution, and
  any successor IDs;
- for each failed or errored check, the headline summary, then every unsupported
  claim with its verdict, its specific reason, and its citation URLs;
- the decision basis that closes each check.

The view keeps the claim-level reason a repair depends on, so the fix is never
hidden behind a broad diagnostic category. It reads only the fields the read API
already returns to you: `guidance`, `resolution`, and the scrubbed
`check_feedback` projection. It makes no extra server call. The `json` and
`jsonl` contracts and the journal format stay unchanged.

### Retire a submission

`retire` withdraws or supersedes one of your open submissions.

- To withdraw the proposal, pass no `--successor` option.
- To supersede the proposal, pass one or more `--successor UUID` options. Each
  option names an explicit newer replacement.
- To record an optional reason, pass `--reason TEXT`.

```sh
oag retire 00000000-0000-0000-0000-000000000001 --force --reason "stale"
oag retire 00000000-0000-0000-0000-000000000001 --force --successor UUID --output json
```

`retire` requires `--force`. Without `--force`, it refuses, sends nothing, and
exits 2. A success reports the server's disposition (`withdrawn` or
`superseded`) and exits 0. The command does not poll afterward. Use `status` or
`watch` to follow the retired submission and its successors. See the retire
entry under [Reference](#retire) for the full behavior and the server rules.

### Recover after a timeout and reconcile a journal

A watch timeout does not mean a submission failed. Resume its journal. Inspect
the lifecycle and the terminal evidence.

Reuse the original submit journal and idempotency keys after an uncertain
create. Never start a duplicate batch to beat a deadline.

A pacing timeout reports the lane, the reserved wait, the remaining budget, and
the requests that the client sent. Submit journals keep this diagnostic with the
original idempotency key. Watch adds `deadline_error` to unresolved records and
saves it in the watch journal. Watch keeps earlier read errors and submission
snapshots. Resume the same journal with a larger budget after you investigate
shared load. Never clear the pacing file to skip a cooldown. Never delete the
journal to retry uncertain submissions.

Some older entries have no keys. The client cannot replay them safely. Inspect
your submissions on the server across all statuses. Compare the complete payload
and the submitter. Once you positively identify an ID, associate it with the
input row:

```sh
oag reconcile batch.json --journal batch.journal.json --row 2 --id UUID
```

This checks that the ID is readable. You verify the row-to-ID match. It does not
create or edit a server submission. If no match turns up, absence is not proof
of failure. Reconcile with an administrator before you create a new batch and
journal.

A server `409 idempotency_key_reused` also needs inspection. Do not mint a fresh
key for the uncertain write. The effective callback URL must stay the same for a
retry; a change to a token's default callback can cause that conflict.

For a definitively failed row, correct the payload. Submit a new batch with a
new journal. Existing submissions are immutable. To supersede a stalled open
create, inspect the existing submission. Then set `"force": true` in a new
payload and submit with a new journal. The client never adds `force`. The client
never edits an existing proposal. Keep prior journals for audit.

### Research a product's coverage gaps

Run `oag coverage PRODUCT --output json` for one compact report of a product's
coverage and its unknown scored fields. The default text output adds evidence
guidance. Read each gap's shared semantics, its schema reference, and its
absence page class before you draft. Keep unsupported values unknown. A
confirmed absence can improve coverage without improving the AI-native score.
Use submission validation to inspect projected changes after you collect
evidence.

### Share pacing across workers

To coordinate workers on one host, point them at the same pacing directory, the
same API origin, and the same token. Set `OAG_PACING_DIR` to choose the
directory; it defaults to `oag-client-pace` under the system temp directory. The
client then shares its reservations and Retry-After cooldowns across those
processes, so they stay under the server's quotas together. The population
benchmark and the pi submitter opt into this coordination.

Separate directories, hosts, origins, or tokens do not share state. Server
quotas apply account-wide across all of an account's tokens, so coordinate
workers on other hosts or other tokens yourself. Python `Client` instances pace
in process unless you pass `shared_pacer(base_url, token)`.

Shared pacing cuts collisions. It does not guarantee that requests dodge
throttling. For how the shared file works, see
[How shared pacing and deadlines work](#how-shared-pacing-and-deadlines-work).
For the pacing numbers and rate-limit scopes, see
[Pacing and deadlines](#pacing-and-deadlines).

### Use trusted bulk read pacing

Default read spacing is 0.55 seconds. A maintainer can grant your account the
`submissions.bulk_submit_catalogsubmission` permission. With that permission,
set `OAG_READ_SPACING=0.11` for the CLI, or pass `read_spacing=0.11` to
`shared_pacer(base_url, token, ...)`. That targets about 545 reads per minute
under the server's default 600-per-minute trusted read quota
(`BULK_AUTHENTICATED_READ_RATE`).

Coordinate workers on one host with the same spacing, the same token, and the
same `OAG_PACING_DIR`. Keep status reads batched through `watch`. Separate
tokens for one account share the quota but need caller-managed coordination.
Restore 0.55 seconds after a revocation. The server checks the permission on
each request, and clients keep honoring shared Retry-After cooldowns.

Faster reads do not change the write pace. See
[Pacing and deadlines](#pacing-and-deadlines) for the write minimums.

## Reference

### Command synopsis

```sh
oag --version
oag products list
oag products list --search "code review"
oag products list --has-mcp --tier A --category code-generation
oag products list --page-size 50 --all
oag products get <slug> --expand mcp_servers,api_specs
oag products filters --output json
oag organizations list --search anthropic
oag organizations get <slug>
oag people get <slug>
oag get "https://www.openagentguide.com/api/v1/catalog/products/?cursor=..."
oag coverage <slug> --output json
oag validate batch.json --output json
cat batch.json | oag validate - --output jsonl
oag submit batch.json --journal batch.journal.json --output json
oag status 00000000-0000-0000-0000-000000000001 --output json
oag status 00000000-0000-0000-0000-000000000001 --output explain
oag watch --file ids.txt --journal watch.journal.json --timeout 900 --output jsonl
oag watch 00000000-0000-0000-0000-000000000001 --journal watch-one.json
oag retire 00000000-0000-0000-0000-000000000001 --force --reason "stale"
oag retire 00000000-0000-0000-0000-000000000001 --force --successor UUID --output json
oag source-preview https://example.com/pricing --claim "Free tier exists"
oag source-preview https://example.com/openapi.json --api-spec --output json
```

`oag --version` (`-V`) prints the installed version and exits 0.

#### products

`products list` lists products. `products get PRODUCT` reads one product by slug
or UUID.

- `--search TEXT` runs a free-text search.
- `--category SLUG`, `--organization SLUG`, and `--tier TIER` filter the list.
  Repeat any of them for OR matching.
- `--has-mcp` and `--no-has-mcp` filter on MCP presence.
- `--filter KEY=VALUE` passes any other server filter. Repeat for more. Run
  `products filters` to list every accepted filter.
- `--expand RELATIONS` includes related records, comma-separated.
  `--fields FIELDS` selects top-level fields, comma-separated.
- `--page-size N` sets the page size. `--cursor TOKEN` reads one page from a
  cursor. `--all` follows every `next` link and prints one JSON array of all
  rows.

`products filters` lists every filter the list command accepts. It reads the
live OpenAPI document and prints each filter's name, type, description, and
allowed values. `--output json` returns the same contract as a machine-readable
object. `organizations filters` and `people filters` do the same for their list
commands.

A single-page read prints the server envelope. `--all` prints a JSON array of
the result rows. Catalog reads work anonymously. A failed read exits 3 with the
server's sanitized envelope on stderr.

#### organizations

`organizations list` lists organizations; `--search` matches names, slugs, and
URLs. `organizations get ORGANIZATION` reads one organization by slug or UUID.
Both commands take `--expand`, `--fields`, `--page-size`, `--cursor`, and
`--all` with the same meaning as `products`.

List responses use cursor pagination. The `CursorPageSchema` envelope holds
`count`, `results`, `next`, `previous`, `page_size_default`, and
`page_size_max`. Follow the absolute `next` link until it is `null`, or pass
`--all`.

#### people

A person publishes a product in place of an organization. `people list` lists
people; the list endpoint has no free-text search, so `--name` matches an exact
name and `--filter slug=...` or `--filter affiliation_id=...` applies the other
filters. `people get PERSON` reads one person by slug or UUID. Both commands
take `--expand`, `--fields`, `--page-size`, `--cursor`, and `--all` with the
same meaning as `products`. Most readers reach a person through
`products get <slug> --expand person` instead.

#### get

`get PATH` is the escape hatch for a read the named commands do not cover: a
pagination `next` link, or a submissions read-API path. It prints the server
body as JSON on one line. `PATH` is a relative read-API path or a same-origin
absolute URL, so a `next` link passes straight back without stripping its
origin. The client accepts an absolute `PATH` only when its scheme and host
match `OAG_BASE_URL` with no userinfo. A foreign origin, userinfo, an
unsupported scheme, or a path outside the catalog or submissions read API exits
2 without a request. Catalog reads work anonymously. The submissions field
contract needs `OAG_TOKEN`.

#### coverage

`coverage PRODUCT` reads one product's coverage gaps and its unknown scored
fields. It calls `GET /api/v1/catalog/products/<slug-or-uuid>/coverage/`. The
default text output adds evidence guidance for each gap. `--output json` prints
one compact report. `coverage` reads anonymously. A failed read exits 3 and
wraps the server error in a `{"version": 1, "error": {...}}` envelope.

#### source-preview

`source-preview URL` previews the verifier's selected evidence for one source
before you spend a submission. It runs one paced, authenticated POST; the server
runs the verifier's fetch ladder and returns the selected text, snapshot hashes
and lengths, completeness, a source-change comparison and failure diagnostics.
The client never fetches the URL itself. Repeat `--claim` for up to 20 claims
and pass the same claims and source mode you will submit so the selection
matches; `--complete-source` previews an absence source as a whole and
`--api-spec` a declared API specification. `--expected-source-sha256` reports
whether the source changed since an earlier preview. JSON/JSONL print the server
report unchanged; text prints a concise view. A successful preview exits 0; an
endpoint failure (including a preview quota 429) exits 3 with the shared failure
envelope; input or configuration errors exit 2. Preview needs `OAG_TOKEN`, never
corroborates a claim or authorizes publication, and warms the server's one-hour
fetch cache, so submitting the same URL within the hour reuses the fetch instead
of re-paying.

#### validate and submit

`validate` and `submit` take one JSON object or an array. The input comes from a
file or from `-` for stdin. Nested relation envelopes and explicit nulls pass
through unchanged. Omitted keys stay omitted. Validation calls the server and
returns its field-path errors. It does not probe external citation URLs. The
batch preflight script still covers that separate check.

#### status and watch

`status` fetches one submission with all its checks and reviews pages. `watch`
polls unresolved IDs in batches of up to 100
(`ids=...&page_size=100&fields=id,status,review_ready,check_feedback,guidance`).
Pending records hold that compact snapshot. When an ID goes terminal, watch
fetches its full detail and every checks and reviews page. Watch keeps claim
verdicts, rationales, citations, and resolution reasons.

The lifecycle maps to a terminal status:

- Only lifecycle `merged` counts as `accepted`.
- An ordinary `closed` is `rejected`.
- A `closed` proposal with a retirement disposition reports `withdrawn` or
  `superseded`. Replacement IDs appear in `resolution.closed.successor_ids`.
- A check error on an open submission stays `pending`.
- A failed detail read or evidence read becomes `failed-to-read`, even after a
  terminal lifecycle was seen. Missing batch IDs stay `failed-to-read` too.

Watch retries unresolved records in later rounds. It stops revisiting a terminal
record only after it captures the record's evidence. The journal keeps those
terminal snapshots across restarts. Start a fresh journal for a fresh view of
later evidence. The server must support the `ids` filter.

#### retire

`retire` withdraws or supersedes one of your open submissions:

- With no `--successor` option it withdraws the proposal.
- One or more `--successor UUID` options supersede it with those explicit newer
  replacements.
- `--reason TEXT` records an optional reason.

`retire` makes one request and never retries. `--force` is required; without it
`retire` refuses, sends nothing, and exits 2. The tool never withdraws or
supersedes on your behalf. The server enforces author-or-curator permission and
newer-only successors. A success reports the server's disposition (`withdrawn`
or `superseded`) and exits 0. A 403 or a validation error exits 3. The command
does not poll afterward. Use `status` or `watch` to follow the retired
submission and its successors.

#### Reading guidance

`status` and `watch` request `guidance` and keep its `next_action` code. For
direct API reads, request `guidance` alongside `status`, `resolution`, and
`check_feedback`. The codes:

- `wait`: keep watching.
- `prepare_correction`: prepare the repair now, but wait for terminal closure
  before you submit it.
- `revise_and_resubmit`: inspect the rejection, correct the proposal, then
  validate against the current catalog.
- `none`: read the terminal resolution, including any successor links.

Guidance never reserves an identity. Guidance never bypasses create conflicts.
If guidance is absent, fall back to lifecycle status. Never infer rejection from
a check error. Preserve your submit and watch journals.

### Output formats

Every command takes `--output text|json|jsonl|explain`. JSON holds `version`,
`records`, and `summary`. JSONL emits one `type: record` line per result, then a
`type: summary` line. Output lands at completion, including watch cancellation.
Watch also emits changed next-action guidance to stderr as it runs. Text prints
the full record with indented evidence. Then text lists any check feedback and
absence-attestation guidance, one scannable line each. You see why a row needs
work without digging through the JSON. Diagnostics go to stderr. No command
prompts.

A failed read keeps the server's structured error. Every `failed-to-read` record
carries a `failure` object with a `kind`. The `kind` is `http`, `deadline`,
`transport`, or `client`. An `http` failure also carries `http_status`, plus the
server's `code`, `detail`, and validation `errors` when present. The
human-readable `error` string stays too. `coverage` wraps the same object in a
`{"version": 1, "error": {...}}` envelope on failure and exits 3. Its successful
report is unchanged.

### Exit codes

| Exit | Meaning                                                              |
| ---- | -------------------------------------------------------------------- |
| 0    | Validation/submission succeeded, or all watched records are terminal |
| 2    | Invalid arguments, configuration, input, or journal                  |
| 3    | At least one failed/ambiguous batch row or failed-to-read record     |
| 4    | Pending records remain at the deadline or in one-shot status         |
| 5    | All records were read, but `--require-all-merged` found a rejection  |
| 130  | Cancelled by Ctrl-C                                                  |

Failures outrank pending records. Pending records outrank
`--require-all-merged`. By default a fully read rejection exits 0, because
watching finished. Pass `--require-all-merged` to status or watch to require
acceptance. Summaries always separate accepted, rejected, pending, and
failed-to-read. Batch summaries also count valid, created, failed, and ambiguous
rows.

### Pacing and deadlines

`--timeout` is an overall seconds budget. It is 300 for validate and submit, 60
for status, and 900 for watch. It covers pacing waits, requests, retries, and
cooldowns. Watch pauses 15 seconds between rounds. Ctrl-C ends watch with a
final summary and exit 130. Its journal can resume. A hard kill cannot emit a
summary.

The client spaces reads 0.55 seconds apart and mutations 3.5 seconds apart.
Validation POSTs use the mutation pace. Requests have a 45-second budget, capped
by the remaining workflow deadline. Validation and keyed creates retry transport
failures, 5xx, and transient 429s, up to five attempts. Unkeyed writes retry
only transient 429s. Polling makes one attempt per round.

Future mutation reservations leave the read schedule unchanged. Create and
validate use the mutation lane. Globally throttled writes such as review, merge,
close, and retire share the read lane and keep a 0.55-second minimum even when
reads run faster. If a peer extends Retry-After during a wait, the worker
reserves a fresh slot to keep spacing after the cooldown. Cancelled or expired
reservations stay on their lane until their slots pass. Restart preserves them.
Custom `Pacer.reserve` implementations must accept `global_mutation=False`.

The rate-limit scopes are `global_auth` for reads, and `submission` and
`submission_burst` for submission mutations. Workers that do not use the
client's shared pacing must pause every worker on the exhausted
`X-RateLimit-Scope` for at least its `Retry-After` seconds, with jitter, before
they resume.

### Sizing batches

Size batches against the combined workload. Fifty validation POSTs followed by
fifty create POSTs need about 350 seconds of mutation spacing alone, before
network time, retries, cooldowns, or other workers' reservations. Those are
separate command budgets. Raise `--timeout` per command for its share of the
work. Leave extra time for watch to capture terminal evidence. More concurrent
processes do not raise shared throughput. Prefer smaller batches, fewer
simultaneous validators and submitters, and one watcher per account that holds
all unresolved IDs. Use one pacing directory for concurrent validate, submit,
and watch commands.

### Environment variables

- `OAG_TOKEN`: the bearer token. Generate one in your account settings. Catalog
  reads work without it. The submissions field contract needs it.
- `OAG_BASE_URL`: the API origin. It defaults to
  `https://www.openagentguide.com`. It cannot contain credentials, a path, a
  query, or a fragment.
- `OAG_PACING_DIR`: the pacing directory. It defaults to `oag-client-pace` under
  the system temp directory. Cooperating processes must share it.
- `OAG_READ_SPACING`: the read spacing in seconds. The default is 0.55. Set it
  to 0.11 with the `submissions.bulk_submit_catalogsubmission` permission.

### Python API

```python
from oag_client import Client, shared_pacer
from oag_client.transport import HTTPTransport
from oag_client.workflows import payloads, validate

base_url = "https://www.openagentguide.com"
# Omit `pacer` for in-process pacing; pass `shared_pacer` to coordinate with
# other processes on this host that share the token.
client = Client(HTTPTransport(token), base_url, pacer=shared_pacer(base_url, token))
records = validate(client, payloads(json_text), deadline=client.clock.monotonic() + 60)
```

`submit`, `status`, `watch`, `summary`, and `exit_code` also come from
`oag_client.workflows`. `Journal` lives in `oag_client.journal`. The `Clock` and
`Transport` protocols make testing deterministic. A custom transport must accept
the optional `idempotency_key` keyword and forward it as `Idempotency-Key` on
create requests. The HTTP transport is synchronous, so async callers should use
a worker thread. Application code supplies authorization. Pacing is in process
by default. Pass `shared_pacer(base_url, token)` (or any `Pacer`) to coordinate
processes that share a directory, an origin, and a token on one host. Coordinate
other tokens or hosts yourself, because server quotas cover the whole account.

## Explanation

### How journals and idempotency keys keep submissions safe to retry

Always reuse the same submit journal for a batch. The journal binds the ordered
input hash, the base URL, and the token fingerprint. Changed inputs,
environments, or tokens fail instead of replaying. The journal never stores
tokens. The journal holds server evidence and may hold private submission data,
so keep it private.

Each new row gets a random UUID `Idempotency-Key`. The client flushes the key to
the journal before the first POST. Every attempt and restart reuses that key and
the same input. A confirmed `201` records the original submission ID as
`created`, even if the server already merged or closed it. The client skips
confirmed and definitively failed rows on restart. Keyed ambiguous or pending
rows retry within the command's deadline. Exhausted transient failures stay
unresolved.

Journal writes are atomic and flushed to disk. A lock prevents simultaneous
writers. After a hard kill, confirm that no writer remains before you delete the
`.lock` file. Never delete a journal to recover from a timeout. Never change a
journal's keys to recover from a timeout. A deadline or cancellation after an
uncertain attempt preserves its key.

The client uses semantic versioning. JSON output stays version 1. New and saved
journals use version 2. Version-1 journals stay readable, but unkeyed uncertain
rows need manual reconciliation. Older clients reject version-2 journals. An
upgrade alone never sends requests and never rewrites journals. Running `submit`
resumes keyed uncertain rows. Pair the client with a server that supports the
create `Idempotency-Key` contract.

### How shared pacing and deadlines work

The client spaces reads and mutations to stay under the server's quotas. The
`oag` CLI shares reservations and Retry-After cooldowns across processes on one
host when the processes use the same pacing directory, API origin, and token.
The filename hashes the origin and a one-way token fingerprint, so separate
directories, hosts, origins, or tokens do not share state. The file stores
timestamps, never the raw token. A crash releases the file lock but keeps its
recorded reservations, so a restart preserves them.

A transient 429 extends the shared cooldown to the longest value that any
cooperating process reports. The client honors numeric and HTTP-date Retry-After
values within the workflow deadline, across reads and mutations together.

Shared pacing cuts collisions. It does not guarantee that requests dodge
throttling. Server quotas apply account-wide across all of an account's tokens,
so coordinate separate tokens and separate hosts yourself. More concurrent
processes do not raise shared throughput. The open-submission-cap 429 returns
immediately without a retry.

A watch timeout does not mean a submission failed. Resume the journal and
inspect the lifecycle and the terminal evidence. The journal and the idempotency
keys make an uncertain create safe to retry without a duplicate.
