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.

  1. 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.
  2. 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.
  3. The internal key is never the instruction. It rides in a setting field 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 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:

What happens when a person presses the button:

  1. One row is kept (admin_ask): who, what, for which account or repository. A repeat is the same ask.
  2. 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.
  3. 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/admin is 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

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:

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:

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs