Linearis — tickets through the tenant mirror

The customer's tenant mirrors their Linear and GitHub state. Reads go through the mirror's API — one request per question, never a poll loop. Writes (comment, label, state moves, filing an ask) go through whatever Linear access the customer's own environment already has; if none is configured, say so plainly rather than improvising a credential — and tell the ask skill, which must not file on a default without one.

baseUrl, key, and account come from ~/.config/catalyst-cloud/customer.json (written by catalyst-skills join). Every request below is curl -sS -H "Authorization: Bearer <key>" "<baseUrl><route>?account=<account>&…".

Reading a ticket — freshness first, then the row

A stored row is only as current as the mirror's last successful pass, and the row itself does not say when that was. So a ticket read is two requests: the freshness probe, then the row.

1. Gate on the freshness probe — GET /api/v1/freshness?account=<account>. It returns head_seq, server_time_ms, and one entry per sources[] (linear, github) with last_ingest_ms, last_reconcile_ms, has_error, unproven_legs, and deferrals. Read the linear entry and classify before trusting anything:
   • fresh: server_time_ms - last_reconcile_ms under 15 minutes, has_error is false, unproven_legs is [].
   • stale: last_reconcile_ms older than 15 minutes, or has_error is true, or unproven_legs is non-empty.
   • inconclusive: last_reconcile_ms is null, or has_error / unproven_legs is null — the mirror could not answer, which is not the same as healthy.
2. Then read the row — GET /api/v1/issues/<id>?account=<account> (the Linear identifier, e.g. ABC-123, or the id).

Report the verdict with the answer: a stale or inconclusive read is delivered as stale or inconclusive ("as of <last_reconcile_ms>, the mirror's Linear pass is N minutes old / errored"), never as current. Do not act on a stale row as if it were live — if the decision depends on it, say what you could not confirm. Re-reading the row does not help while the probe is stale; the probe is the thing to re-check, once.