When a setting or a permission stands in the way
An error that says a setting or a permission stops the reader holds to three rules.
- It says it in the reader's terms. A full sentence about what they were doing: "This forge is hosted by forge.example.com, which has not allowed it to reach git.example.com yet." Never the name of a key.
- It knows whether this reader can change it. If they can, it links straight to the exact control (a page and its anchor, like
/settings/hosted-forges#reach). If they cannot, it says who can and offers the one action that asks them. - The internal key is never the instruction. It rides in a
settingfield for an agent or a log.
The helper
blockedBy (src/kernel/blocked.ts) builds one value every surface renders:
blockedBy({
says: "No agents exist on this forge yet.",
readerCan: user.isAdmin,
link: { href: "/settings/crew", label: "Add an agent" }, // used when readerCan
who: "an admin of this forge", can: "add one", // used when not
askAction: { method: "POST", path, body, label }, // the one action that asks them, when there is one
setting: "the.internal.key", // for agents and logs
});
- A page draws it with
blockedNote(the sentence and one button or link) orblockedWay(the way through alone, after a sentence already on the page):src/web/blocked.ts. - An API or MCP answer spreads
blockedFields(b)besideerrorandmessage:says, thenfix: { href, label }orwhoandask: { method, path, body }, thensetting. Every such error carries its next step as data. - A terminal, a log or a stored summary prints
blockedText(b).
A button on a page posts the ask as a form to the page's own route, with the action's body as its fields, so the page and the agent cannot drift.
Asking whoever can
A reader who cannot change it is offered one action, and there are two, by who holds the control:
- The host of this forge (a name its gate has not opened):
POST /api/v1/reach/asks,docs/features/ask-to-reach.md. - An admin of this forge, or of one repository:
POST /api/v1/asks/admin { want, subject }(src/actions/ask_admin.ts).wantis one of a fixed list (WANTS,src/actions/blocked_words.ts): a model grant, a model account, a spend ceiling, a model key, a private destination, an email verified, membership, the telemetry grant, an agent, a repository's crew. Each names the exact control, with the page's own anchor on the field (/settings/accounts/bob#f-grant,/settings/crew#crew-key).
What happens when a person presses the button:
- One row is kept (
admin_ask): who, what, for which account or repository. A repeat is the same ask. - The one who answers sees it counted in their home page's one line ("1 person is stopped until you answer"), which links to
/asks. There it is listed under "Stopped until you answer": "bob asks for a model grant for bob (2 minutes ago)", linked to the control, with Not now beside it. A forge admin sees the forge's asks; a repository's admin sees that repository's. - When the thing is there (the grant exists, the key is saved, the email is verified) the ask is done by itself.
GET /api/v1/asks/adminis how the asker, or an agent, reads how it stands.
On a page the button is askButton (src/web/blocked.ts): it submits one hidden form the layout draws for every signed-in reader, so it works inside a paragraph, a flash or another form. An API answer carries blockedFields; an MCP refusal is built with badBlocked and carries the same fields as structuredContent.
In the terminal the same thing is the palette command What stands in the way (src/tui/screens/asks_admin.ts), for anyone signed in. It lists what waits on you to answer, what stands in your own way now (no model key, no model budget) and what you asked, in the sentences the page says. a sends the ask for the row, o opens the control for one who can change it, n is Not now.
A sentence stored before its reader is known
A run's summary, a park comment and a log line are read by anyone. They are stored as the sentence and who can, in words (storedText: "This forge has no model key. An admin of this forge can add one."), never a path or a key name. A surface that knows its reader calls wayIn(app, reader, text) and draws the link or the button from it: the run's page does.
Where it is used
- Model keys, grants, accounts, ceilings and budgets: a run's stop (
src/crew/runner.ts,forge_budget.ts,src/core/account_ceiling.ts,subscriptions.ts), the key card on every page that draws it, "Land it as it is", Settings → Connect your AI, and talking to the forge's agent (page, API, MCPsay). - A private destination an app asks for: both rows on the app's settings, and the gate's own refusal.
- Mail: no mail, and the day's mail spent (the resend on Settings, the API, MCP
email_verify). - A guest proposing a change (membership), no agents on this forge, the telemetry grant (MCP
flow,system,telemetry_history), a repository's crew (MCPcrew). - A hosted forge refused by its host's gate (
gateBlocked).
What is held
test/refusals-lead-somewhere.test.ts reads every sentence in src/ that tells its reader to ask someone or says someone else must act. A new one that is not built by the helper fails. Three kinds are allowed, each written down there:
- A role statement ("Only a forge admin sets a budget."): the reader tried another role's act on a door that could not hide it. Nothing is set to let them, so nothing is linked.
- Terminal, each with its reason: the reader is signed out, the owner is on another host, or the sentence already gives the reader's own way through.
- Waiting, each with what it waits on: the terminal's row for a private destination, a lost note (no control restores one), a run's ungranted secret, and a hosted forge's lent credit (the host takes no ask for it yet).
test/ask-admin.test.ts opens every control as the one who can and finds the field the link names, and sends every ask as one who cannot.
A setting that does not lift the refusal
Found while wiring the links, and not changed here:
- Talking to the forge's agent refuses "no model account" from subscription grants alone (
pickSubscription). A model grant in dollars, which is what an admin gives on an account's page and what a crew run accepts, does not lift it. The ask therefore points at Settings → Subscriptions, not at the account's grant. - The crew's limits (
/settings/crew#budgets) are drawn only on a forge another one hosts, which is also the only place they stop a run, so the link is right where the sentence can appear and nowhere else. - The telemetry grant can be given to an agent only, so a person is told who reads those figures and is offered no ask.