@hanzo/build 0.2.51 → 0.2.53

package/README.md

@@ -65,6 +65,15 @@ under the mount (`path`) and how to move (`go`), where to link out
 (`theme`, `chooseTheme`), which follows the person's saved choice. Peers:
 `@hanzo/ui`, `@hanzo/gui`, `@hanzogui/lucide-icons-2`, `react`.
 
+`path` is the builder's own grammar (`route`, `path`). A host that shows real
+paths writes it with `href` and reads it back with `parse`: '' New,
+`/run/<id>`, `/projects/<org>/<repo>` a repository, `/projects/<slug>` a site,
+`/machines` and `/environments` in the rail's own words, and every other place
+at its name (`/projects`, `/issues`, `/customize/connectors`, `/settings/usage`).
+`PLACES` lists every address that names no record, for a host that writes a page
+per address ahead of time. `@hanzo/build/route` is that module alone, with no
+React, for server code and for pages that must not carry the builder.
+
 ### In a host that has its own rail
 
 The Hanzo app already has a left column, so it mounts `<Builder host={host}
@@ -74,7 +83,7 @@ rail={false} />` in its pane and lists the builder in its own rail:
 import { Builder, DevSection } from '@hanzo/build'
 
 <Sidebar>            {/* the host's rail, @hanzo/ui/chat */}
-  <DevSection host={host} />   {/* New run, Artifacts, Templates, the runs */}
+  <DevSection host={host} />   {/* every place, grouped (nav), then the runs */}
 </Sidebar>
 <Builder host={host} rail={false} />
 ```
@@ -85,11 +94,24 @@ pane tokens: `--pane-fill`, `--pane-round`, `--pane-edge`, `--pane-blur`,
 `--pane-gap`, and `--shadow-sheet-2` for the drop. A host retunes the tokens;
 it writes no rule against the builder's slots.
 
-`DevSection` is rows of `@hanzo/ui/chat`'s Sidebar; `useSessions(host)` is its
-data — the org's coding runs, kept live by the org's feed — for a host that
-draws the rows itself. `administers(token, org)` reads the org-admin bit off a
+`DevSection` is rows of `@hanzo/ui/chat`'s Sidebar; `nav(host, go)` is the one
+list of places every rail draws, in groups (Work, Make, Run, Setup) and with
+nothing behind a More; `useSessions(host)` is the runs — the org's coding runs,
+kept live by the org's feed — for a host that draws the rows itself. `administers(token, org)` reads the org-admin bit off a
 hanzo.id token for `Host.admin`. One left column, never two.
 
+## The model, the composer, the panel
+
+One of each, shared with Chat (@hanzo/rooms imports them):
+
+- `useMind` — the model and effort: `GET /v1/models` read once per platform,
+  and the choice kept in this browser (`hanzo.mind`, Enso and Medium until
+  changed). `Tune` is the chip that changes it; Settings → Code writes the same
+  choice. `@hanzo/build/mind` serves the store alone, without the builder.
+- `prompt` / `Prompt` — the composer, as wide as the text above it (`measure`).
+- `Reply` — copy, Listen and Open under an answer.
+- `Panel` over `useDeck` — the side panel and its kept tabs.
+
 ## Addresses
 
 | path | screen |
@@ -98,29 +120,45 @@ hanzo.id token for `Host.admin`. One left column, never two.
 | `sess_<32 hex>` | one run, live |
 | `-/automations` | repeating work, read from `/v1/auto/flows` |
 | `-/customize` · `-/customize/connectors` · `/plugins` · `/agents` | Customize: skills, connectors, plugins, agents |
-| `-/mcp` | Connectors → Discover, where the fleet's native MCP servers now live |
-| `-/codebases` | the forge's repositories |
-| `-/sync` | bring granted repositories onto the forge |
-| `-/projects` | the forge's boards |
-| `-/issues` | the forge's issues |
+| `-/mcp` | Connectors → Browse with the fleet's native MCP servers listed |
+| `-/projects` | the org's projects: its repositories on the forge |
+| `-/sync` | link repositories from GitHub onto the forge |
+| `-/issues` | every project's issues, merged: the forge's and the task index's |
 | `-/artifacts` | what the org has built |
 | `-/templates` | the public starters |
 | `-/plans` | the plans this brand sells, and the move to another |
 | `-/settings/<section>` | Billing, Usage, Members, Integrations, Notifications, … |
-| `<slug>` | a project's workspace |
+| `<org>/<repo>` | a project's workspace: the repository, and its site when it has one |
+| `<slug>` | a deployed site's workspace |
 
-A project slug holds no `_` and never starts with `-`, so the forms cannot
-collide.
+A project slug holds no `_` and never starts with `-`, and a repository is the
+one address of two segments, so the forms cannot collide.
 
 ## What is on the screen
 
+**Issues.** Every project's issues and pull requests, the forge's and the task
+index's merged (merge.ts): the same issue on two boards is one row, with every
+label and assignee either carried. A column of projects — every board, and every
+repository an issue is filed under — each with what is open on it; Open and
+Closed with their counts; a search; Label, Assignee, Kind, Source and Sort.
+Pressing an issue opens New on the issue's own repository, where the issue
+lives (a GitHub issue on GitHub, a forge issue on the forge), filled with its
+title, number, link and body, and the run's pull request closes it; an issue no
+project answers to (a Linear team's key, a board with no repository) asks which
+project it is for. A board's key is never taken for a repository.
+
 **The rail** (this page, or `rail` left on). At the top, the mark. Signed in to an organization,
 that spot is the organization switcher: the org, and the projects under it.
-New, Projects, Artifacts, Customize, Automations, then More (Codebase, Issues,
-Templates, Machines, Docs), then the org's coding runs newest first with a live
-status dot. At the foot, a card offering Hanzo in Slack (dismissed once, gone in
-this browser) and the account, whose menu holds the email, Settings, Usage, View
-all plans, Get help (the docs, in a new tab) and Log out. Collapse is an explicit
+New, then every place in view (nav.tsx) — Work: Projects, Issues; Make:
+Artifacts, Templates, Automations; Run: Machines, Environments; Setup:
+Customize, Docs — then the org's coding runs newest first with a live status
+dot. Nothing waits behind a More. At the foot, a card offering Hanzo in Slack
+(dismissed once, gone in this browser) and the account, whose menu holds the
+email, the plan under it
+(`Meter`: Max with 20x beside it and the session, day and month as shares;
+Free's allowance left today; the balance only with no plan), Settings, Usage,
+Billing, View all plans, Get help (the docs, in a new tab) and Log out. No money
+sits beside a plan: credits live in Billing. Collapse is an explicit
 toggle kept in this browser. A host with its own rail draws `DevSection` there
 instead.
 
@@ -136,35 +174,44 @@ drain, claim key (shown once) and removal. API keys: your secret and publishable
 key, a new one shown once, rotated or revoked.
 
 **Customize.** What the agent brings to a run, a tab each — Skills, Connectors,
-Plugins, Agents — and in each, Yours (what the org has) and Discover (what it
-can add), one search and one Add. Skills and connectors ride into every run in
-the org, so they are an org admin's to add, switch and remove, and a member reads
-them; plugins and agents are any member's.
-
-- Skills: the org's own SKILL.md skills, written, revised and deleted here, and
-  the brand's catalogue (`/.well-known/agent-skills/`) to read and add. Adding is
-  switching `skill_<name>` on, and a switch per skill turns it off again.
-- Connectors: the MCP servers the org added — by URL or off the shelf, a secret
-  sealed in KMS — each with a switch per tool. Adding one switches its tools on.
-  Discover is the shelf (featured first; a listing that ships only a package has
-  no plus) and the fleet's native servers `POST /v1/mcp` lists, which every run
-  can call and nothing adds.
+Plugins, Agents — and in each, Browse (what there is to add, then what Hanzo
+builds in) first and always where the tab opens, then Yours (what the org has,
+counted on its button); one search and one Add. An empty Yours names the next
+step as buttons. A read that fails is said in plain words with Try again, and one
+that takes over fifteen seconds gives up and says so; only a 400, 409 or 422
+carries the platform's own sentence (a failed build, a name taken). Skills and
+connectors ride into every run in the org, so they are an org admin's to add,
+switch and remove, and a member reads them and is told so; plugins and agents
+are any member's.
+
+- Skills: Browse is the brand's catalogue (`/.well-known/agent-skills/`) to read
+  and add; Yours is the org's own SKILL.md skills, written, revised and deleted
+  here, and the catalogue's it added. Adding is switching `skill_<name>` on, and
+  a switch per skill turns it off again.
+- Connectors: Browse is the shelf (featured first; a listing that ships only a
+  package says so and has no Add), then the fleet's native servers, which every
+  run can call and nothing adds — listed by `POST /v1/mcp` only when asked for,
+  since that list starts every subsystem it names. Yours is the MCP servers the
+  org added — by URL or off the shelf, a secret sealed in KMS — each with one
+  switch on its card for all its tools and one per tool inside. Adding one
+  switches its tools on.
 - Plugins: TypeScript connectors built on the platform, from source or from a
-  description of an API; a failed build says why. Discover lists what the
-  deployment mounts.
-- Agents: the org's own — model, instructions, tools, budget — created, edited
-  (only what changed is sent) and deleted; Discover is the platform's presets
-  whose tool calls run on the platform.
+  description of an API; a failed build says why. Browse offers building one and
+  lists what the deployment mounts.
+- Agents: Browse is the platform's presets whose tool calls run on the platform,
+  each a Use that opens a new agent written from it; Yours is the org's own —
+  model, instructions, tools, budget — created, edited (only what changed is
+  sent) and deleted.
 
 **New.** "What's up next?", and at the foot the composer: where the run runs
 (Cloud is the platform's sandbox with the codebase's environment; the org's
 machines follow under remote control, each linked with `hanzo link`), the
 codebase and the branch — the forge's repositories, filtered as you type, read
 again with Refresh list, and a way to Sync for a GitHub repository that is not
-there yet — then the ask. Under it: attach (files ride the prompt as text),
-dictate, Build or Plan, and the model and effort. A codebase can be added to a
-project. Opening a codebase or an issue from its own screen lands here with
-that choice already made.
+there yet — then the ask, in the composer Chat draws too (`prompt`): the paperclip
+and Build or Plan at its start; the model and effort (`Tune`), dictation and
+send at its end. A codebase can be added to a project. Opening a codebase or an
+issue from its own screen lands here with that choice already made.
 
 **A run.** The transcript as it streams, drawn by what each part is: what the
 agent says as markdown, each command it runs as a card that opens onto its
@@ -174,17 +221,14 @@ request once it pushes one. Once it has finished, a follow-up starts a new run
 from the branch it pushed — the same codebase, place and mode — and opens it; a
 paused sandbox run goes on the same way. A plan run ends with its plan and
 Approve and build. Rename it, share a project run's story publicly, and find any
-run by status in Find. Beside it:
-
-- Environment: the codebase's environment, and the run's facts.
-- Git: what it pushed, read from the forge — Diff, Review, Commits.
-- Desktop: its sandbox's screen, framed from the sandbox's own noVNC page. A
-  sandbox run asks for a desktop.
-- Terminal: a shell in the same working tree (a tmux session named for the run,
-  so it reattaches), and the agent's own log.
-- Files: the working tree live from the sandbox, or the run's branch; and
-  Artifacts, what it produced.
-- Subscriptions.
+run by status in Find. Beside it, the side panel (`Panel`, the one Chat opens):
+Preview (what the sandbox serves, or where the run is published), Artifacts,
+Files, Diff (Diff, Review, Commits) and Terminal (a shell in the working tree,
+reattached by the run's name, and the agent's log); `+` opens Desktop (the
+sandbox's screen), Environment and any page. Tabs are dragged to reorder (or
+moved with Ctrl/⌘+Shift+←/→), shut with their cross, and kept as left; the
+header's Panel button and ⌘. / Ctrl+. open and shut it, and a phone opens it as
+a sheet. An answer's Open shows what it wrote there, and a publish opens Preview.
 
 The desktop and the shell are the sandbox's, so they close when the run stops.
 The setup bar says how long setup runs here have taken, once there are three.
@@ -222,7 +266,8 @@ picker and open-in-tab; Share and Publish; the console dock under it.
 | `POST /v1/sandbox/read` | the run's working tree, live |
 | `GET /v1/provider/github/repos` · `POST /v1/provider/github/repos/import` | granted repositories, and bringing them onto the forge |
 | `GET /v1/git/repos` · `GET /v1/git/repos/{name}` | the codebase chip, and its branches |
-| `GET /v1/task/projects` · `GET /v1/task/board` · `GET /v1/task/projects/{key}/issues` | boards and issues, read from the forge |
+| `GET /v1/sync` | the repositories linked from GitHub, each with its forge copy and when it last synced |
+| `GET /v1/task/projects` · `GET /v1/task/board` · `GET /v1/task/projects/{key}/issues` | boards, and every issue and pull request: the forge's and the task index's |
 | `GET /v1/provider/github/repos` · `…/{owner}/{repo}/branches` | kept for a host that still asks GitHub |
 | `POST /v1/provider/github/user/connect` | connect a person's GitHub |
 | `GET /v1/projects` · `PATCH`/`DELETE /v1/projects/{slug}` · `POST /v1/projects/fork` · `GET /v1/templates` | artifacts, templates |
@@ -245,14 +290,17 @@ picker and open-in-tab; Share and Publish; the console dock under it.
 | `GET /v1/billing/plans` · `…/subscriptions` · `POST …/subscribe/card` · `…/subscriptions/{id}/cancel`·`/reactivate` | Plans, and the plan in Billing |
 | `GET`/`POST`/`DELETE /v1/billing/methods` · `GET /v1/billing/settings` | saved cards; a card is added from the processor's own field |
 | `GET /v1/billing/invoices` · `…/invoices/{id}/pdf` | invoices |
-| `GET /v1/billing/balance` · `…/credit-balance` · `…/usage/rollup` · `POST …/topup` · `GET /v1/usage/summary` | Usage |
+| `GET`/`PUT /v1/ai/limits` · `GET /v1/billing/tier` · `GET /v1/allowance` | the plan's windows as shares, and credits past the allowance (Usage, the menu's `Meter`) |
+| `GET /v1/billing/balance` · `…/credit-balance` · `…/credits` · `…/usage/rollup` · `GET`/`PUT …/recharge` · `POST …/topup` · `GET /v1/usage/summary` | Credits, in Billing: prepaid, granted, top-up, auto-reload, spend |
 | `GET`/`POST`/`PATCH`/`DELETE /v1/billing/alerts` | the monthly limit (org admin) |
 | `GET /v1/iam/memberships?org=` · `GET`/`POST`/`DELETE /v1/iam/invitations` | Members |
 | `GET /v1/provider/{slack,github}` · `POST …/connect`·`/disconnect` · `GET /v1/provider/slack/channels` · `GET /v1/provider/github/installations` | Integrations |
 | `GET`/`POST /v1/webhook` · `DELETE /v1/webhook/{id}` · `POST …/test` · `GET …/deliveries` | Notifications |
 
-`mode`, `model` and `effort` are sent with a run as asked; the platform
-honours them where it does and nothing here simulates them.
+`mode`, `model` and `effort` are sent with a run as asked — Enso as
+`enso-auto`, never left out — and `issue`, the number a run started from an
+issue closes; the platform honours them where it does and nothing here
+simulates them.
 
 ## Layout
 
@@ -261,11 +309,16 @@ src/
   index.ts      the library surface
   builder.tsx   the rail and the pane the address names
   landing.tsx   New
-  forge.tsx     Codebase, Automations, Projects, Issues
+  forge.tsx     Automations, Projects, Issues
+  merge.ts      what is the same project and the same issue, which repository an issue is for
   run.tsx       one run
   transcript.tsx  a run's transcript, as cards
   prose.tsx     markdown, drawn as text (markdown.ts reads it)
   desk.tsx      the pane beside a run
+  mind.ts       the model and effort, one choice with Chat
+  prompt.tsx    the composer, and Tune, the model and effort chip
+  reply.tsx     the row under an answer
+  panel.tsx     the side panel; tabs.ts its kept tabs
   pane.ts       how a pane is cut, from the --pane-* tokens
   door.tsx      a run's desktop or shell, framed
   git.tsx       what a run pushed
@@ -273,6 +326,7 @@ src/
   environment.tsx a codebase's environment
   project.tsx   a project's workspace
   shelf.tsx     Artifacts and Templates
+  nav.tsx       the places, once, for every rail
   customize/    Customize: the shell, then one file per tab
   publish.tsx   Add to project / Publish
   find.tsx      finding a run, by status, paged

package/lib/api/billing.d.ts

@@ -15,6 +15,10 @@
  *   GET    /v1/billing/invoices/{id}/pdf         the invoice as a PDF
  *   GET    /v1/billing/balance                   prepaid balance, whole cents
  *   GET    /v1/billing/credit-balance            granted credit, per currency
+ *   GET    /v1/billing/credits                   {grants}: every grant, spent and lapsed included
+ *   GET    /v1/billing/tier                      the rung served and its tier class
+ *   GET    /v1/billing/recharge                  the auto-reload rule
+ *   PUT    /v1/billing/recharge                  arm it (a card on file) or disarm it
  *   POST   /v1/billing/topup                     charge a saved card into the balance
  *   GET    /v1/billing/usage/rollup              the plan's month: included spend and request windows
  *   GET    /v1/usage/summary?range=month         this month's spend, by category
@@ -167,6 +171,41 @@ export declare function pdf(t: Target, id: string): Promise<Blob>;
 export declare function balance(t: Target): Promise<number>;
 /** Granted credit the org can spend, in US cents. */
 export declare function credit(t: Target): Promise<number>;
+/** One grant of credit, spent, lapsed and voided included: the ledger, not the spendable figure. */
+export interface Grant {
+    id: string;
+    name: string;
+    amount: number;
+    remaining: number;
+    currency: string;
+    /** RFC 3339, or '' for one that does not lapse. */
+    expires: string;
+    active: boolean;
+}
+export declare function grants(t: Target): Promise<Grant[]>;
+/** The rung an organization is served as (`max-20x`, '' with none) and the tier class it is served under (`pro`). */
+export interface Tier {
+    plan: string;
+    tier: string;
+}
+export declare function tier(t: Target): Promise<Tier>;
+/** Auto-reload: top the balance up by `amount` whenever it falls below `threshold`, charging the card on file. */
+export interface Recharge {
+    enabled: boolean;
+    threshold: number;
+    amount: number;
+    currency: string;
+    /** RFC 3339 of the last reload, or ''. */
+    last: string;
+}
+/** The rule as stored; one never set reads as off. */
+export declare function recharge(t: Target): Promise<Recharge>;
+/** Arm or disarm the rule. Turning it on needs a card on file, and the platform says so when there is none. */
+export declare function arm(t: Target, rule: {
+    enabled: boolean;
+    threshold: number;
+    amount: number;
+}): Promise<Recharge>;
 /** Charge a saved card and add the amount to the balance; answers the balance after. */
 export declare function topup(t: Target, amount: number, card: string): Promise<number>;
 export interface Window {

package/lib/api/billing.js

@@ -15,6 +15,10 @@
  *   GET    /v1/billing/invoices/{id}/pdf         the invoice as a PDF
  *   GET    /v1/billing/balance                   prepaid balance, whole cents
  *   GET    /v1/billing/credit-balance            granted credit, per currency
+ *   GET    /v1/billing/credits                   {grants}: every grant, spent and lapsed included
+ *   GET    /v1/billing/tier                      the rung served and its tier class
+ *   GET    /v1/billing/recharge                  the auto-reload rule
+ *   PUT    /v1/billing/recharge                  arm it (a card on file) or disarm it
  *   POST   /v1/billing/topup                     charge a saved card into the balance
  *   GET    /v1/billing/usage/rollup              the plan's month: included spend and request windows
  *   GET    /v1/usage/summary?range=month         this month's spend, by category
@@ -255,6 +259,43 @@ export async function credit(t) {
         .filter((b) => (str(b.currency) || 'usd').toLowerCase() === 'usd')
         .reduce((sum, b) => sum + num(b.available), 0);
 }
+export async function grants(t) {
+    const raw = obj(await call(t, 'GET', '/v1/billing/credits'));
+    return arr(raw.grants)
+        .map(obj)
+        .map((g) => ({
+        id: str(g.id),
+        name: str(g.name),
+        amount: num(g.amountCents),
+        remaining: num(g.remainingCents),
+        currency: str(g.currency) || 'usd',
+        expires: str(g.expiresAt),
+        active: g.active === true && g.voided !== true,
+    }))
+        .filter((g) => g.id);
+}
+export async function tier(t) {
+    const r = obj(await call(t, 'GET', '/v1/billing/tier'));
+    return { plan: str(r.plan), tier: str(obj(r.tier).name) };
+}
+function recharged(raw) {
+    const r = obj(raw);
+    return {
+        enabled: r.enabled === true,
+        threshold: num(r.thresholdCents),
+        amount: num(r.amountCents),
+        currency: str(r.currency) || 'usd',
+        last: str(r.lastRechargedAt),
+    };
+}
+/** The rule as stored; one never set reads as off. */
+export async function recharge(t) {
+    return recharged(await call(t, 'GET', '/v1/billing/recharge'));
+}
+/** Arm or disarm the rule. Turning it on needs a card on file, and the platform says so when there is none. */
+export async function arm(t, rule) {
+    return recharged(await call(t, 'PUT', '/v1/billing/recharge', { enabled: rule.enabled, thresholdCents: rule.threshold, amountCents: rule.amount, currency: 'usd' }));
+}
 /** Charge a saved card and add the amount to the balance; answers the balance after. */
 export async function topup(t, amount, card) {
     if (!Number.isInteger(amount) || amount <= 0)

package/lib/api/coding.d.ts

@@ -50,8 +50,11 @@ export interface Ask {
     /** An earlier run's session to continue from, on the branch it pushed. */
     after?: string;
     mode?: Mode;
+    /** The model the agent thinks with, by the id GET /v1/models lists; Enso is sent as itself. */
     model?: string;
     effort?: string;
+    /** The number of the issue on `repo` this run resolves: its pull request says `Closes #<n>`. */
+    issue?: number;
 }
 export interface Run {
     session: string;
@@ -65,7 +68,7 @@ export interface Run {
  * A run in the sandbox asks for one with a desktop, so its Desktop tab has a
  * screen to show; a machine is whatever it is.
  */
-export declare function body(ask: Ask): Record<string, string | boolean>;
+export declare function body(ask: Ask): Record<string, string | number | boolean>;
 export declare function start(t: Target, ask: Ask): Promise<Run>;
 /** A run a follow-up continues, as its record states it. */
 export interface Earlier {

package/lib/api/coding.js

@@ -45,6 +45,8 @@ export function body(ask) {
         if (v)
             out[k] = v;
     }
+    if (ask.issue && Number.isInteger(ask.issue) && ask.issue > 0)
+        out.issue = ask.issue;
     if (!out.targetId)
         out.desktop = true;
     return out;

package/lib/api/environment.d.ts

@@ -37,6 +37,18 @@ export interface Environment {
     updated: string;
 }
 export declare function environment(raw: unknown, repo?: string): Environment;
+/**
+ * Whether a codebase still waits to be set up: nothing proposed and nothing ever
+ * saved. Skip & save keeps an empty environment, which the platform answers as
+ * state `none` with the time it was saved (apps/environment `view`), so the
+ * time is what tells a choice made from one never made.
+ */
+export declare const unset: (e: Environment) => boolean;
+/**
+ * What a refused save or setup run says to the person who pressed it: what is
+ * wrong and what to do, in the reader's words rather than the platform's.
+ */
+export declare function plain(e: unknown, repo: string, act: 'save' | 'start' | 'run'): string;
 export declare function environments(t: Target): Promise<Environment[]>;
 export declare function read(t: Target, repo: string): Promise<Environment>;
 export declare function save(t: Target, repo: string, scripts: {

package/lib/api/environment.js

@@ -14,7 +14,7 @@
  * here as `proposal` until someone saves it. Secrets are names only; their values
  * are sealed in KMS and reach the run's environment, never this record.
  */
-import { call, seg } from './call.js';
+import { call, Refusal, seg } from './call.js';
 const str = (v) => (typeof v === 'string' ? v : '');
 const obj = (v) => (v && typeof v === 'object' ? v : {});
 const names = (v) => (Array.isArray(v) ? v.filter((n) => typeof n === 'string' && n !== '') : []);
@@ -34,6 +34,44 @@ export function environment(raw, repo = '') {
         updated: str(o.updatedAt),
     };
 }
+/**
+ * Whether a codebase still waits to be set up: nothing proposed and nothing ever
+ * saved. Skip & save keeps an empty environment, which the platform answers as
+ * state `none` with the time it was saved (apps/environment `view`), so the
+ * time is what tells a choice made from one never made.
+ */
+export const unset = (e) => e.state === 'none' && !e.updated;
+/**
+ * What a refused save or setup run says to the person who pressed it: what is
+ * wrong and what to do, in the reader's words rather than the platform's.
+ */
+export function plain(e, repo, act) {
+    // This page's own refusals (a secret's name, an empty value) are already a reader's words.
+    if (e instanceof Error && !(e instanceof Refusal) && e.name === 'Error' && e.message)
+        return e.message;
+    if (e instanceof Refusal) {
+        const why = e.message;
+        if (e.status === 401)
+            return 'Your session ended. Sign in again, then try again.';
+        if (e.status === 403 && act === 'save')
+            return 'Only an organization admin saves an environment. Start the agent instead; an admin reviews what it proposes.';
+        if (e.status === 402)
+            return 'This run needs a plan with runs left. See Plans to change it.';
+        if (e.status === 403)
+            return `This account cannot start a run on ${repo}. Ask an organization admin for access.`;
+        if (e.status === 429)
+            return 'Too many runs are going right now. Try again in a minute.';
+        if (e.status >= 500)
+            return act === 'save' ? 'The environment store is not answering right now. Try again shortly.' : 'The code workspace is not answering right now. Try again shortly.';
+        if (/no repository named|not one of this organization|is not a repository/.test(why))
+            return `${repo} is not a repository this organization has on the forge. Choose one of its repositories.`;
+        if (/no account on the forge|verify .* first|no forge identity/.test(why))
+            return 'Your forge account is not ready yet: sign in to the forge once, then try again.';
+    }
+    if (act === 'save')
+        return `The environment for ${repo} could not be saved. Try again.`;
+    return act === 'start' ? `The setup run on ${repo} could not start. Try again.` : `The run on ${repo} could not start. Try again.`;
+}
 export async function environments(t) {
     const r = await call(t, 'GET', '/v1/environment');
     return (Array.isArray(r?.data) ? r.data : []).map((e) => environment(e)).filter((e) => e.repo);

package/lib/api/github.d.ts

@@ -8,6 +8,7 @@
  *   POST /v1/provider/github/user/complete     {grant} → the connection
  *   POST /v1/provider/github/user/disconnect
  *   GET  /v1/provider/github/installations     the accounts this org has bound the App on
+ *   POST /v1/provider/github/issues/backfill   {state, repo?} → mirror GitHub issues onto the board
  *
  * Paged by an opaque `after` cursor; `next` is the cursor for the page after
  * this one, or empty on the last. Rows are read defensively: a field the
@@ -31,6 +32,8 @@ export interface Repo {
     pushed_at: string;
     /** The App installation that grants access, or 0 for the person's own grant. */
     installation_id: number;
+    /** The name it takes on the forge once brought there: `owner_name`, folded. */
+    codebase: string;
 }
 export interface Repos {
     repos: Repo[];
@@ -105,9 +108,11 @@ export interface Grant {
     fullName: string;
     private: boolean;
     branch: string;
-    /** Already mirrored onto the forge. */
+    /** The name it takes on the forge once brought there. */
+    codebase: string;
+    /** On the forge: linked and landed, or held there under its codebase name. */
     imported: boolean;
-    /** `synced`, `conflict`, or '' while it has not landed. */
+    /** `synced`, `conflict`, `pending`, `paused`, or '' while it is not linked. */
     status: string;
 }
 export interface Grants {
@@ -121,10 +126,43 @@ export interface Account {
     /** Named as unread and carrying no repositories. */
     blocked: boolean;
 }
+/**
+ * One row of GET /v1/provider/github/repos (apps/provider github_index.go
+ * repoView): `owner`, `name`, `full_name`, `private`, `default_branch`,
+ * `pushed_at`, `installation_id`, `codebase`. Whether it is on the forge is not
+ * in the row — `codebase` is the name it would take, not a sign it has — so
+ * `imported` is decided by `grants` from the links and the forge.
+ */
 export declare function grant(raw: unknown): Grant | null;
 /** Accounts the grant names, plus any account that could not be read. */
 export declare function accounts(g: Grants): Account[];
-/** Every repository the GitHub connection grants, with whether the forge already has it. */
+/**
+ * Every repository the GitHub connection grants, every page, with whether the
+ * forge already has it: a link that has landed (GET /v1/sync, its `native`
+ * state), or a forge repository under its codebase name (GET /v1/git/repos).
+ */
 export declare function grants(t: Target, signal?: AbortSignal): Promise<Grants>;
+/** What an import queued: how many, and the name each takes on the forge, by `owner/name`. */
+export interface Queued {
+    queued: number;
+    codebases: Record<string, string>;
+}
 /** Queue a mirror of the named repositories onto the forge. The names are `owner/name`. */
-export declare function bring(t: Target, repos: string[]): Promise<number>;
+export declare function bring(t: Target, repos: string[]): Promise<Queued>;
+/** What one issue sync did. */
+export interface Synced {
+    repos: number;
+    issues: number;
+    created: number;
+    updated: number;
+    failed: number;
+    /** The pass stopped at its budget; syncing again continues where it stopped. */
+    truncated: boolean;
+}
+/**
+ * Mirror GitHub issues onto the board — open and closed, so a closed one reads as
+ * closed here too. `repo` (`name` or `owner/name`) syncs one project; empty syncs
+ * every repository the connection grants. Idempotent: a second sync updates and
+ * never duplicates, and the App's webhook keeps them live afterwards.
+ */
+export declare function syncIssues(t: Target, repo?: string): Promise<Synced>;