mesh-catalog/modules/claude-licence-manager/README.md

# claude-licence-manager

Holds the `anthropic-licence-manager` seat: every Anthropic licence the mesh has, kept alive by one
rotation source, its consumers moved off a licence near its limit by the manager itself (novox/hq ADR 0183,
ADR 0206, design 39 and its milestone bus-and-switch). Every grant and access token lives in the vault; this module
keeps none.

## How a licence comes to exist

Nothing is configured. Every node running `claude-code` says what it holds as the event
`claude-code.holdings-changed` (the account, fingerprints and expiries, never a token), at its start, on every change,
and again when this module says `holdings.asked` (at every start, after the carry-over, and on `licences_resync`):

1. A report with a refresh token it does not hold is a **candidate**.
2. It asks that node's `claude_code_grant`, giving its public key, and receives the grant sealed to it.
3. **It refreshes it**, under the account's lease. If the vendor exchanges the token, the licence is new, named by its
   account's address and kept under that name's key (`@` as `_at_`, any other character outside letters, digits, `-`
   and `.` as `_`); its grant and access token go to the vault (`licence-put`), and from then on this module is the
   only refresher. If not, the candidate is recorded dead and nothing is adopted. An adoption whose key another licence
   has is refused.
4. Several nodes logged in to one account: newest login first; the rest are never exchanged.
5. The node it came from is bound to it; a node reporting that account and bound to nothing is bound to it.

From its next reading a new subscription has a room and is a target of the switch. An API key enters through `adopt`,
from a file on this module's node or sealed by a node's `claude_code_add_api_key`; it is never a target.

## What it keeps on the bus

Each piece asked for in `requires` by its template (ADR 0595), read by `licences_kept`:

| name | template | what |
|---|---|---|
| `licences` | state, history 1 | one key per licence: account, address, organisation, expiries, failures, adoption, the vault's generation, the latest reading; never a token |
| `bindings` | state, history 8 | one key per consumer (a node's name): licence, kind, generation, since, why and by |
| `leases` | state, a lifetime per key | `licence.<key>`, `account.<id>`: one refresh or adoption at a time, two minutes |
| `offered` | state, a lifetime per key | each grant a node offered and its outcome, 90 days |
| `usage` | log, 35 days, 256 MiB | every reading, one subject per licence key, with the vendor's answer whole |
| `audit` | log, 64 MiB | every act, one subject per kind (`switched`, `carried`, `settings` among them) |
| `carried` | state | `postgres`: when the carry-over ran, and per table the rows read and entries written |
| `conditions` | state | each condition said raised, and since when |

Its database (`postgres-database`, read with the module's own credential) and `grant.key` are kept only as the
carry-over's source: at its first start, before it hears an event, refreshes or reads usage, the manager reads every
row of today's six tables and writes them here and to the vault, then `carried.postgres`. Until then it serves its
reads alone and answers every act with "the carry-over has not ended"; a failed read or write raises
`carry-over-failed`. With `carried.postgres` present it never reads the database again. The database is never written.

## Switching on usage

Every `usage_minutes` the manager reads each subscription's usage with its access token from the vault: the session,
weekly and sonnet windows, each with its reset time. A licence's room is 100 less the higher of its session and weekly
percentages, known only when it was read within `usage_stale_minutes` and its refresh is healthy. When a reading puts
a licence with consumers at or above `switch_at_pct`, every consumer bound to it moves, in one act, to the licence
with the most room whose windows are both below `room_below_pct`: one `binding.changed` per consumer, one
`licence.switched`, and one `operator-channel.tell`. A consumer is never moved back by the rule.

Its conditions are said on the operator channel's condition subject, the router deciding where they go:
`licence.<key>.no-room` (urgent; no licence has room), `licence.<key>.near-limit` (at `warn_at_pct`, once per
crossing), `licence.<key>.usage-unread`, `carry-over-failed` and `settings.<setting>.invalid`.

## The seat's verbs

`licences`, `bindings` (with `consumer` for one), `bind`, `switch`, `release`, `refresh`, `usage` (`licence`,
`since`, `limit` up to 2000, `raw`), `adopt`, `public-key`, `current` (the licence, its key, kind, generation and
health, never the token) — through the console as `anthropic-licence-manager.<verb>`. No answer carries a token.

## Its tools

`licences_switches` (every switch and why), `licences_read_usage` (read now, `dry`), `licences_switch_now` (apply the
rule now, even with `switch_auto` off), `licences_settings` (each value, its default and where it was set),
`licences_kept` (every entry it keeps, how full against its cap), `licences_resync` (say every binding, holdings.asked
and each condition again, and hand each access token to the vault again), `licences_conditions`, `licences_carried`
(the carry-over's record; `run` while it has not ended).

## Settings

Through mesh-config, each `trusted`, read again at every reading: `cadence_minutes` (240), `floor_minutes` (60),
`failures_to_notify` (3), `cooldown_hours` (24), `refresh_warn_days` (3), `switch_auto` (on), `switch_at_pct` (99,
1 to 100), `room_below_pct` (90, 1 to 100), `warn_at_pct` (90, 1 to 100), `usage_minutes` (5, 1 to 60),
`usage_stale_minutes` (15, 5 to 180). A value outside its bound keeps its default and raises its condition.

## Events

`licence.adopted`, `licence.refused`, `licence.switched`, `licence.failing`, `usage.read`, `binding.changed`,
`holdings.asked` — none carries a secret. It consumes `claude-code.holdings-changed`.

## Code and tests

Go, one binary (`cmd/claude-licence-manager`): the seat's verbs, the tools and the daemon in one launched bundle. The
sealed box is `claude-code`'s own format, byte for byte — the two modules carry the same `seal.go` — and a test opens
one sealed by the TypeScript agent module the Go one replaced, so the format is the one already on the machines.

    go test ./...
    # the whole module on a real bus, and today's rows on a real postgres:
    go test -tags integration ./...

The whole tests (`whole_integration_test.go`) start the built binary as its runtime does, its kept data in a real
nats-server, and today's database on `MESH_TEST_POSTGRES` or a private postgres started from the machine's `initdb`
on a socket of its own; with neither, the tests that need one skip and say so. The vault, the agent modules, the
operator channel and the vendor are played beside it; a condition is read through the operator channel's client.

## Files it does not know

Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).

- `${dir:state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).