pi-roundtable 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-16
+
+### Added
+
+- `Roundtable.check()` and `RegistrationReport` (`pi-roundtable`): sets up every plugin as `run()` would and refuses what `run()` refuses (a plugin that adds nothing, a clash, a missing service, a removed field, a bad route), with the same messages, without migrating the database, starting a service, opening a listener or reaching Discord. It resolves the plugins that run, the services they add in start order and their routes. A plugin whose `setup` queries the database fails the check with `plugin <name>: setup failed: the database was queried during setup…`, which says to query from a service's `start`; the built-in identity sync and the skills and agent stores skip their load under it. It runs no preflight and does not count as a running host. It runs each plugin's `setup`, so check a definition you do not run: the built-in agent server binds its sessions once, which makes the plugin objects of a checked definition impossible to run or check again, and `roundtable doctor` and `start` therefore check a definition assembled again, with the configuration file evaluated again (Bun runs it again under a new query), so the plugins it makes with a factory are new objects. The file's top-level code therefore runs twice under `doctor` and `start`; keep side effects out of it. When the file was not evaluated again, because the runtime did not run it or because its default export is built in a module it imports, the check fails and says so; build the definition in `roundtable.config.ts` itself. A plugin object that a module the file imports exports is shared, and so is state kept at module level, so a plugin's `setup` must keep nothing one-shot outside its call. As `run()` does, it sets the process's locale, time zone and, when `environment.agentDir` is set, `PI_CODING_AGENT_DIR`. The identity sync settles under it only what the configuration and the declared identities settle without a stored principal. The registration moved out of `src/core/host.ts` into one shared module, and `run()` behaves as before.
+- `requireDatabase`, `usePostgresForTests` and `UsePostgresOptions` (`pi-roundtable/testing`). `requireDatabase()` gives the test database's URL and throws, naming how to provide one, when the run has none. `usePostgresForTests({ binDirs?, require? })` is for a test preload: unless `ROUNDTABLE_TEST_DATABASE_URL` is set, it starts a throwaway PostgreSQL on `127.0.0.1` (trust authentication, `fsync` off, a temporary data directory), sets the variable and `testDatabaseUrl`, and stops and removes it after the run; with `require: true` it throws when `initdb` or `postgres` is not found.
+- `TestHost.runTool(name, args, options?)` and `TestHost.hold(name, args, options?)` (`pi-roundtable/testing`): run a contributed tool in the owner's session as a speaker on a channel and read the text the model would read (a refusal comes back as its text, as with `testPlugin`'s `runTool`; any other error throws), and ask the tool's hold what it would show for the call. `testPlugin`'s `runTool` shares the code that runs the tool.
+- The `codex-images` template takes `onMissingLogin: "throw" | "warn"` in `createCodexImages`. The default `"throw"` keeps today's behavior, where a host without an `openai-codex` login refuses to start; `"warn"` logs one warning at setup and lets the host start, and a drawing then fails with the same `PluginError`.
+- Per-surface formatting guidance. A chat surface tells the model how its replies render, and the runtime appends that text to the system prompt of every turn that replies on the surface, after the persona and everything appended before it; an agent answered on Discord with Markdown tables, which Discord shows as raw `|` pipes. The new optional `ChatSurface.formatting` is a short English text, and the surface is found from the channel the turn replies in, so one persona can answer on several surfaces with each one's rules. A turn whose channel has no surface, and a surface without `formatting`, add nothing. The built-in values: Discord says Markdown renders except tables (use bullet lists or `key: value` lines), and that a reply over 2,000 characters is split; `pi-roundtable-line` says LINE shows plain text only; `pi-roundtable-webchat` says full Markdown renders, tables included. A host overrides or removes a value through that surface's options: `discord.formatting` in the configuration, `formatting` in `line({ ... })` and `webChat({ ... })`; a text replaces it and `false` tells the model nothing, and an empty text is refused. `RuntimeDeps.formatting(channel)` gives a custom runtime provider the same lookup, and the runtime of `pi-roundtable/testing` is handed it too. `pi-roundtable-web` has no reply surface and is unchanged.
+
+### Changed
+
+- `testPlugin` runs the plugin's `preflight` after it is set up and before its services start, as the host does, and a `preflight` that throws fails `testPlugin` with that error. A plugin that does its start-up reading there (such as `pi-roundtable-mcp`'s) works under `testPlugin` as it does on a host.
+- **Breaking for plugins that read `CONNECTORS` while they set up (`pi-roundtable-mcp`):** `mcpConnectors` and `remoteMcp` set up without querying the database or reaching the gateway, so `Roundtable.check()` passes with them; they do that work in their `preflight`, before any service starts. `CONNECTORS.list()`, `servers()` and `profileSources()` are empty during `setup`, and `version` changes once they are loaded; read them from a service's `start` or later (see the package changelog).
+- `roundtable doctor` and `roundtable start` run `Roundtable.check()`, on a definition assembled again for the purpose, in the offline `plugins` check, after the duplicate-name check, and print the message `run()` would fail with. A configuration with a plugin that adds nothing, or any other registration clash, now fails before `start` migrates the database or contacts Discord.
+- `testDatabaseUrl` and `describeDb` (`pi-roundtable/testing`) are live exports (`declare let`): `usePostgresForTests()` updates them after the module has loaded. Reading them is unchanged.
+- Every package's core peer range moves to `>=0.17.0 <0.18.0`.
+
 ## [0.16.0] - 2026-10-16
 
 ### Changed

package/README.md

@@ -196,6 +196,11 @@ When a conversation is started over in a server channel or thread, the assistant
 | text | `─── new conversation ───` | The divider's text |
 | `false` | | Post no divider |
 
+| `discord.formatting` | Default | What it is |
+| --- | --- | --- |
+| text | Markdown renders except tables | What the model is told, in English, about how a reply renders in Discord; appended to the system prompt of every turn that replies there |
+| `false` | | Tell the model nothing |
+
 An approval card or an `ask_user` question holds its turn for `discord.cardGraceSeconds` (default `120`).
 The files of a message in an agent's channel download within `discord.attachmentDownload.deadlineMs` (default 60,000) for the message and the one it replies to together, and a file that sends no byte for `discord.attachmentDownload.idleMs` (default 10,000) is given up; the turn goes on without a file it could not get.
 The copy button of an approval card keeps its text in `card-copies.json` under the data directory, the newest 100 for 30 days; `discord.cardCopies` (`{ keepDays?, keep? }`) changes that, and `false` keeps them in memory only.

package/docs/plugins.md

@@ -2348,6 +2348,10 @@ It is not posted in a direct message or on another surface, and a failed post is
 The text is `discord.freshMarker` (default `─── new conversation ───`); `false` posts none.
 A surface a plugin contributes may implement the optional `ChatSurface.markFresh(channel)` for the same job.
 
+Discord does not render Markdown tables, so the Discord surface tells the model about it: every turn that replies in a Discord channel gets a short guidance text appended to its system prompt, after the persona.
+The default says that Markdown renders except tables, that bullet lists or `key: value` lines replace them, that headings, bold, lists, quotes, inline code, fenced code blocks and `-#` small text work, and that a reply over 2,000 characters is split.
+`discord.formatting` replaces the text; `false` tells the model nothing.
+
 The block gives each author as a name, their Discord id and a role (`owner`, `bot` or `member`) in separate attributes, and says the messages were not addressed to the assistant. A name loses the characters `"`, `'`, `=`, `<`, `>`, `(`, `)` and `,`, so it cannot imitate another author, an attribute or a role, and every `<` (also the full-width `＜`) in a message's text is replaced by `‹`, so a message can neither close the block nor open a message of its own.
 `ChannelContext` is `{ messages, text, images? }`: `messages` are `ChannelContextMessage`s (`id`, `authorId`, `authorName`, `bot`, `owner`, `text`, `at`, `attachments`), oldest first, `text` is the block, and `images` the fetched images (see above).
 `ChannelContextOptions` holds the options above, and `CHANNEL_CONTEXT_DEFAULTS` their defaults.
@@ -2549,6 +2553,7 @@ The agent server claims only `discord:` keys, so claims on your surface's channe
 | `start(deliver)` | Connects, and calls `deliver(message)` for every incoming message; the host passes its conversation router | (required) |
 | `sendReply(channel, reply)` | Posts an `OutboundReply`: a thinking line, a card, text chunks, then files | (required) |
 | `stop()` | Disconnects when the host stops | nothing to stop |
+| `formatting` | A short English text on how a reply renders here, such as "no Markdown tables"; the runtime appends it to the system prompt of every turn that replies on this surface, after the persona | nothing is appended |
 | `startTyping(channel)` | Shows a typing indicator until the returned function is called | none is shown |
 | `showStop(channel)` | Shows the owner a stop control until the returned function is called; using it calls `conversations.stop(channel)` | none is shown |
 | `react`, `unreact` | Adds or removes the bot's reaction on a message | no marks on queued or steered messages |
@@ -2556,6 +2561,13 @@ The agent server claims only `discord:` keys, so claims on your surface's channe
 | `interim(channel)` | Where a running turn posts the text it writes before its final answer, as `InterimPosts`: `post(text)` sends one message of at most 2000 characters and resolves to an `InterimMessage` whose `edit(text)` changes it in place | only the final reply is posted |
 | `progress(channel, event)` | Shows a turn run through `context.turns` as it goes, such as a live preview in a web chat. `event` is a `TurnProgress`: `{ type: "text", delta }` (the reply's text, joined over 250 ms and always sent before a tool event, never the thinking), `{ type: "tool_start", id, tool, preview? }` (a one-line preview of the arguments, at most 80 characters, never their full text), or `{ type: "tool_end", id, tool, ok, refused? }` (`refused`, only on a failed end that a hold refused, says how: `declined` on its approval card, `expired` when a card was shown and went unanswered, `pending` while the card stays open, or `held` when no card could be shown (no one may approve it, or it could not be posted); it is absent for a success and for a real failure). The final reply still comes through `sendReply`; a rejection is logged and the turn goes on | only the final reply is shown |
 
+A surface tells the model how its replies render with `formatting`: a short English text, kept under about 400 characters, which the runtime appends to the system prompt of every turn that replies on the surface, after the persona and everything appended before it, for the channel the turn replies in.
+One persona can answer on several surfaces, so the guidance comes from the surface and never from the persona.
+A turn whose channel has no surface, and a surface without `formatting`, add nothing.
+The built-in values: Discord says that Markdown renders except tables, which show as raw pipes, so the model writes bullet lists or `key: value` lines instead; the `line` surface says it shows plain text only; the web chat says full Markdown renders, tables included.
+A host overrides or removes a built-in value through that surface's options (`discord.formatting`, `line({ formatting })`, `webChat({ formatting })`): a text replaces it, and `false` tells the model nothing.
+A custom runtime provider reads the same lookup as `RuntimeDeps.formatting(channel)`.
+
 Each message a surface delivers says who wrote it in `actor`, the `ActorFacts` the identity service resolves: `provider` and `subject`, such as `discord` and the user id, `name`, `roles` written `<surface>:role:<name>` (left out where the surface does not know them, such as a Discord DM, which is not the same as none), and `legacyId`, the speaker id 0.8 gave the person, so someone carried over keeps their principal.
 A surface that leaves `actor` out has it read from `authorId`, `authorName`, and `authorRoleIds` with its prefix as the provider, and the host warns once that this goes away in 1.0.
 
@@ -3233,6 +3245,18 @@ Run every test with `bun test`, and the types with `bun run typecheck`.
 Importing `pi-roundtable/testing` works with `CI=true` and no database URL.
 `describeDb` is Bun's `describe` when `ROUNDTABLE_TEST_DATABASE_URL` is set, and `describe.skip` otherwise; use it to gate a database suite.
 `testDatabaseUrl` is that URL or an empty string, and `TEST_GUILD` is a synthetic guild identifier.
+Both are live bindings: `describeDb` and `testDatabaseUrl` read after `usePostgresForTests()` has run show the database it started.
+`requireDatabase()` gives the URL, and throws an error that says how to provide one when the run has none, for a test file that must not be skipped.
+`usePostgresForTests({ binDirs?, require? })` is for a test preload: unless `ROUNDTABLE_TEST_DATABASE_URL` is already set, it starts a throwaway PostgreSQL on `127.0.0.1` (trust authentication, `fsync` off, a temporary data directory), sets the variable and `testDatabaseUrl`, and stops and removes it after the run.
+It looks for `initdb` and `postgres` in `binDirs` (default `PG_BIN` and the usual Homebrew and Debian directories) and then on `PATH`; with `require: true` it throws when it finds neither, and without it the tests that need a database skip or call `requireDatabase()`.
+Three lines are the whole setup: put `[test]` `preload = ["./test-support/postgres.ts"]` in `bunfig.toml`, and in that file:
+
+```ts
+import { usePostgresForTests } from "pi-roundtable/testing";
+
+await usePostgresForTests({ require: true });
+```
+
 `openTestStore(Store, ...args)` runs the store's `migrations(...args)` or its single `migration`, calls `Store.attach`, and returns a `TestStore<T>` whose `close()` closes its own SQL pool.
 Use it with your own store class in a gated database test, and close the store when the test ends.
 It doesn't attach another instance of the host's stores.
@@ -3270,6 +3294,8 @@ It returns:
 | `commands` | `added`, every slash-command contribution the plugins handed Discord in order, and `composed()`, the tree Discord would register |
 | `sessionTools(scope?)` | The tools each extension of a session registers, in plan order (an extension that registers commands, flags, or event handlers besides tools is accepted, and only its tools are listed); the owner's session unless an `AgentTurnScope` is given |
 | `sessionContext(scope?)` | A `SessionContext` as the runtime builds it, with the real compaction wrapper |
+| `runTool(name, args, { speaker?, channel?, origin? })` | Runs a contributed tool in the owner's session as the speaker on the channel (the owner's channel by default), as `testPlugin`'s `runTool` does, and gives the text the model would read: a tool that throws throws, a refusal (`ToolRefusal`) comes back as its text, and a tool no plugin added throws a `PluginError` |
+| `hold(name, args, { speaker?, channel? })` | What the tool's hold shows for the call, asked as a turn of that speaker on that channel asks it, or `undefined` when the call runs without an approval |
 | `stop()` | Stops the host; call it when the test ends |
 
 `useEagerCatalog()` sets a catalog that marks every text and uses a foreign time zone.
@@ -3278,6 +3304,43 @@ It returns:
 
 `holdChain(rules)` is in `pi-roundtable/kit`: the chain the host links from every plugin's hold rules, to test a rule set without a harness.
 
+### `Roundtable.check()`: prove the registration without a database
+
+`new Roundtable(options, plugins).check()` sets up every plugin as `run()` would and refuses what `run()` refuses: a plugin that adds nothing, two services of one name, a service no plugin provides, a field the host removed, a route that clashes or names a listener that is not configured.
+It migrates nothing, starts no service, opens no listener, reaches no Discord and runs no preflight, so it needs neither PostgreSQL nor the network.
+It runs each plugin's `setup`, so a plugin keeps whatever its setup keeps: the built-in agent server binds its sessions once, so the plugin objects of a definition that was checked cannot be run, or checked again.
+Check a definition you do not run: call `defineRoundtable` again for the check, as `roundtable doctor` and `roundtable start` do (they also evaluate `roundtable.config.ts` again, so the plugins it makes with a factory are new objects), and run the one you did not check.
+The configuration file's top-level code therefore runs twice under `doctor` and `start`: keep side effects out of it (opening a port, writing a file, calling a helper that refuses a second call). If the file was not evaluated again, because the runtime did not run it or because its default export is built in a module it imports, the check fails and says so; build the definition in `roundtable.config.ts` itself.
+What stays shared between the two definitions is a plugin object that a module the configuration imports exports, and state kept at module level: a plugin's `setup` must keep nothing one-shot outside its call, such as a value it binds once and then refuses to bind again, because `doctor` and `start` set the same plugin up twice.
+As `run()` does, it sets three things of the process: the locale and the time zone from the host's `environment`, and `PI_CODING_AGENT_DIR` when `environment.agentDir` is set.
+A check of another host while one runs therefore changes them for the running host, and in one `bun test` process they carry into later test files; give the hosts you check the same `environment`.
+It is no running host: a check never makes `run()` refuse a second host.
+It resolves a `RegistrationReport`: `plugins` (those that run, in set-up order), `services` (those they contribute, in start order) and `routes` (as `<listener> <path>`).
+
+A plugin's `setup` sees a database that refuses every query, so setup may take `database()` and hand it to a store but may not query it: query from a service's `start` or from a handler.
+A plugin that queries during setup fails the check with `plugin <name>: setup failed: the database was queried during setup…`.
+Work that must be done before any service starts, such as reading the stored rows a command or a turn needs at once, belongs in the plugin's `preflight`, which the host runs after every plugin is set up and `check()` never runs.
+The built-in plugins that read or write rows when they attach (the identity sync, the skills and the agent stores) skip that load here and start empty.
+The identity sync still settles what the configuration and the declared identities settle without a stored principal: a plugin identity that names no principal when `access.owners` lists no one to bind it to, and an owner who names their `principal` and lists an identity a plugin binds to another principal.
+What needs a stored principal or link, such as a plugin bound to a principal that does not exist, is left to the start.
+Keep resources out of `setup`; open them from a service's `start`, which `check()` never runs.
+
+Test the production composition with it, since the other tests build their settings by hand:
+
+```ts
+import { expect, test } from "bun:test";
+import { defineRoundtable, Roundtable } from "pi-roundtable";
+import { silentLogger } from "pi-roundtable/testing";
+
+test("the production configuration registers every plugin", async () => {
+	const defined = await defineRoundtable(productionConfig(), { logger: silentLogger() });
+	const report = await new Roundtable(defined.options, defined.plugins).check();
+	expect(report.plugins).toContain("my-plugin");
+});
+```
+
+`roundtable doctor` and `roundtable start` run it in the offline `plugins` check, on a definition assembled again for the purpose (the configuration file is evaluated again too), so a configuration the host would refuse fails before `start` migrates or contacts Discord.
+
 ### `describeSurfaceContract`: what every chat surface keeps
 
 A plugin that contributes a `ChatSurface` can test it against the contract every surface keeps.
@@ -3384,6 +3447,7 @@ These are the messages as the code writes them, with `<...>` where your names go
 | `no persona is registered for the conversation kind "<kind>". A plugin adds one with personas: [...], or its claim must start conversations of a kind that has one.` (a failed turn) | Contribute a persona of that kind, or run the turn with a kind that has one |
 | `no runtime provider is configured: the runtime plugin builds the Pi runtime when no plugin fills the runtime slot; read the running one from services.get(RUNTIME)` | Only a plugin that calls `providers.runtime` without `providers.filled.has("runtime")` sees it; read `services.get(RUNTIME)` instead |
 | `session tool <name> takes a core extension name. Rename it.` | Pick a name other than the core's |
+| `plugin <name>: setup failed: the database was queried during setup…` (from `Roundtable.check()`, `roundtable doctor` or `start`) | A plugin's `setup` ran a query. Take `database()` in setup and query from a service's `start` or from a handler |
 | `two plugins are named <name>.` (from `roundtable doctor`) | Rename yours; the built-in plugins are `memory`, `schedule-store`, `prechecks`, `discord`, `modules`, `discord-admin`, `skills`, `conversations`, `runtime`, `agent-server`, `seeds`, and `schedules` |
 | `migration <plugin>/<name> is declared twice` | A plugin declares two migrations with one name: rename one (the same name in two plugins is fine) |
 | `/<root> <name> is added twice`, `/<name> is registered twice` | Give each slash command and subcommand its own name |
@@ -3683,6 +3747,7 @@ Import from the entries listed below; source area files are internal.
 | `REPLY_FILE_LIMITS` | `pi-roundtable` | value |
 | `RoundtableConfig` | `pi-roundtable` | type |
 | `RoundtableOptions` | `pi-roundtable` | type |
+| `RegistrationReport` | `pi-roundtable` | type |
 | `RoundtablePlugin` | `pi-roundtable` | type |
 | `RouteSocket` | `pi-roundtable` | type |
 | `RuntimeDeps` | `pi-roundtable` | type |
@@ -3791,6 +3856,7 @@ Import from the entries listed below; source area files are internal.
 | `TestPluginOptions` | `pi-roundtable/testing` | type |
 | `TestPluginResult` | `pi-roundtable/testing` | type |
 | `TestStore` | `pi-roundtable/testing` | type |
+| `UsePostgresOptions` | `pi-roundtable/testing` | type |
 | `describeDb` | `pi-roundtable/testing` | value |
 | `describeSurfaceContract` | `pi-roundtable/testing` | value |
 | `checkSurfaceContract` | `pi-roundtable/testing` | value |
@@ -3810,6 +3876,7 @@ Import from the entries listed below; source area files are internal.
 | `openTestStore` | `pi-roundtable/testing` | value |
 | `servicePair` | `pi-roundtable/testing` | value |
 | `partial` | `pi-roundtable/testing` | value |
+| `requireDatabase` | `pi-roundtable/testing` | value |
 | `recordingLogger` | `pi-roundtable/testing` | value |
 | `RecordingLogger` | `pi-roundtable/testing` | type |
 | `RecordedLog` | `pi-roundtable/testing` | type |
@@ -3818,6 +3885,7 @@ Import from the entries listed below; source area files are internal.
 | `testHost` | `pi-roundtable/testing` | value |
 | `testPlugin` | `pi-roundtable/testing` | value |
 | `useEagerCatalog` | `pi-roundtable/testing` | value |
+| `usePostgresForTests` | `pi-roundtable/testing` | value |
 | `useTestLocale` | `pi-roundtable/testing` | value |
 | `AUTO_THINKING` | `pi-roundtable/kit` | value |
 | `AgentCategory` | `pi-roundtable/kit` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/cli/checks/configuration.ts

@@ -1,3 +1,5 @@
+import { Roundtable } from "../../core/host.ts";
+import { silentLogger } from "../../core/log.ts";
 import { CONFIG_FILE, type Project } from "../project.ts";
 import { fail, ok, type Result } from "../report.ts";
 
@@ -7,7 +9,11 @@ export async function checkConfiguration(project: Project): Promise<Result> {
 	return assembled.ok ? ok(`${CONFIG_FILE} is valid`) : assembled.failure;
 }
 
-/** Every plugin has its own name, the operator's and the built-ins' together. */
+/**
+ * Every plugin has its own name, the operator's and the built-ins' together, and the plugins
+ * register as `start` would register them: each set up, each adding something, none clashing,
+ * without a database, a listener or Discord.
+ */
 export async function checkPlugins(project: Project): Promise<Result> {
 	const assembled = await project.assembled();
 	if (!assembled.ok)
@@ -21,6 +27,20 @@ export async function checkPlugins(project: Project): Promise<Result> {
 			);
 		seen.add(name);
 	}
+	try {
+		// A definition of its own: the one `start` runs must not have had its plugins set up.
+		const defined = await project.reassemble();
+		// The plugins' own log lines are the boot's to print, not the check's.
+		await new Roundtable(
+			{ ...defined.options, logger: silentLogger() },
+			defined.plugins,
+		).check();
+	} catch (error) {
+		return fail(
+			error instanceof Error ? error.message : String(error),
+			`Fix the plugin the message names in ${CONFIG_FILE}, or remove it: \`roundtable start\` would refuse it the same way.`,
+		);
+	}
 	const own = assembled.value.config.plugins.map((plugin) => plugin.name);
 	return ok(
 		own.length === 0 ? "no plugins of your own" : `yours: ${own.join(", ")}`,

package/src/cli/project.ts

@@ -8,6 +8,7 @@ import {
 	resolveConfig,
 } from "../core/config/config.ts";
 import type { DefinedRoundtable } from "../core/define-roundtable.ts";
+import { type Logger, silentLogger } from "../core/log.ts";
 import { fail, type Result } from "./report.ts";
 
 export const CONFIG_FILE = "roundtable.config.ts";
@@ -15,29 +16,49 @@ export const CONFIG_FILE = "roundtable.config.ts";
 /** What the command line reaches outside itself, so each check can be run against a fake. */
 export interface Ports {
 	/** The value `roundtable.config.ts` exports by default. */
-	loadConfig(cwd: string): Promise<unknown>;
+	loadConfig(cwd: string, options?: { fresh?: boolean }): Promise<unknown>;
 	/** The bot's options and plugin list, assembled from a valid configuration. */
 	define(
 		config: RoundtableConfig,
 		agentDir: string,
+		overrides?: { logger?: Logger },
 	): Promise<DefinedRoundtable>;
 	/** Where the login for `provider` in `agentDir` comes from, or undefined when there is none. */
 	login(agentDir: string, provider: string): Promise<string | undefined>;
 }
 
-/** Loads the project's configuration file with Bun, which reads `.env` on its own. */
-export async function loadConfigFile(cwd: string): Promise<unknown> {
+/**
+ * Loads the project's configuration file with Bun, which reads `.env` on its own. With `fresh`
+ * the file is evaluated again, so the plugins its default export makes are new objects.
+ */
+export async function loadConfigFile(
+	cwd: string,
+	options: { fresh?: boolean } = {},
+): Promise<unknown> {
 	const path = join(cwd, CONFIG_FILE);
 	if (!existsSync(path))
 		throw new Error(
 			`${CONFIG_FILE} is not in ${cwd}. Run this in the project directory, or create a project with \`roundtable init\`.`,
 		);
-	return loadDefault(path);
+	return loadDefault(path, options);
 }
 
-/** The value a configuration file exports by default, imported with Bun. */
-export async function loadDefault(path: string): Promise<unknown> {
-	const module = (await import(pathToFileURL(path).href)) as {
+let evaluations = 0;
+
+/**
+ * The value a configuration file exports by default, imported with Bun. With `fresh` the file is
+ * imported under a path of its own (Bun evaluates a plain path with a new query again, and not a
+ * `file:` URL with one), so what the file makes at its top level is made again; the modules it
+ * imports stay as they were, shared with the first evaluation.
+ */
+export async function loadDefault(
+	path: string,
+	{ fresh = false }: { fresh?: boolean } = {},
+): Promise<unknown> {
+	const specifier = fresh
+		? `${path}?fresh=${++evaluations}`
+		: pathToFileURL(path).href;
+	const module = (await import(specifier)) as {
 		default?: unknown;
 	};
 	if (module.default === undefined)
@@ -76,6 +97,8 @@ export class Project {
 	readonly #cwd: string;
 	readonly #ports: Ports;
 	#raw: Promise<Loaded<unknown>> | undefined;
+	/** The configuration file's default export as it was loaded, before its adapters were lifted. */
+	#exported: unknown;
 	#assembled: Promise<Loaded<Assembled>> | undefined;
 
 	constructor(cwd: string, ports: Ports) {
@@ -90,7 +113,10 @@ export class Project {
 	 */
 	raw(): Promise<Loaded<unknown>> {
 		this.#raw ??= this.#ports.loadConfig(this.#cwd).then(
-			(value): Loaded<unknown> => ({ ok: true, value: lifted(value) }),
+			(value): Loaded<unknown> => {
+				this.#exported = value;
+				return { ok: true, value: lifted(value) };
+			},
 			(error: unknown): Loaded<unknown> => ({
 				ok: false,
 				failure: fail(
@@ -133,6 +159,31 @@ export class Project {
 		return this.#assembled;
 	}
 
+	/**
+	 * The configuration assembled again, for a check that runs every plugin's setup: the
+	 * configuration file is evaluated again, so the plugins its default export makes with a factory
+	 * are new objects, and the built-in plugins are made again. A plugin object that a module the
+	 * file imports exports is the same object, and so is state kept at module level, so a plugin's
+	 * `setup` must keep nothing one-shot outside its call. The plugins' own log lines go nowhere:
+	 * the definition `start` runs speaks for the host.
+	 */
+	async reassemble(): Promise<DefinedRoundtable> {
+		const assembled = await this.assembled();
+		if (!assembled.ok) throw new Error("the configuration is not valid yet");
+		const fresh = await this.#ports.loadConfig(this.#cwd, { fresh: true });
+		// A runtime that did not evaluate the file again would share every plugin with the first definition.
+		if (fresh === this.#exported)
+			throw new Error(
+				`${CONFIG_FILE} was not evaluated again, so the check would set up the very plugins that start runs. Either this Bun did not run the file again when it was imported under a new query (1.4.2 does), or the default export is built in a module the file imports (\`import config from "./base.ts"; export default config;\`), which stays shared. Build the definition in ${CONFIG_FILE} itself: call defineRoundtable and the plugin factories there.`,
+			);
+		const value = lifted(fresh);
+		return this.#ports.define(
+			value as RoundtableConfig,
+			assembled.value.config.agentDir,
+			{ logger: silentLogger() },
+		);
+	}
+
 	async #assemble(): Promise<Loaded<Assembled>> {
 		const raw = await this.raw();
 		if (!raw.ok) return raw;

package/src/cli/runtime.ts

@@ -4,6 +4,7 @@ import type { Credential, CredentialStore } from "@earendil-works/pi-ai";
 import { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { DefinedRoundtable } from "../core/define-roundtable.ts";
 import { defineRoundtable } from "../core/define-roundtable.ts";
+import type { Logger } from "../core/log.ts";
 
 /** A credential store that holds nothing and refuses writes, so looking never creates `auth.json`. */
 const emptyCredentials: CredentialStore = {
@@ -46,8 +47,10 @@ export async function providerLogin(
 export async function assemble(
 	config: Parameters<typeof defineRoundtable>[0],
 	agentDir: string,
+	overrides: { logger?: Logger } = {},
 ): Promise<DefinedRoundtable> {
 	return defineRoundtable(config, {
 		modelRuntime: await openModelRuntime(agentDir),
+		...(overrides.logger ? { logger: overrides.logger } : {}),
 	});
 }

package/src/core/agents/agent-store.ts

@@ -48,6 +48,8 @@ export {
 	MIN_GROUP_MEMBERS,
 } from "./agent-rules.ts";
 
+import { isCheckDatabase } from "../db/check-database.ts";
+
 /**
  * Agents, groups, and group messages, in the database. Agents and groups are also held
  * in memory, because every inbound message asks and only this process changes them.
@@ -77,7 +79,8 @@ export class PgAgentStore implements AgentDirectory {
 	/** The store over the host's migrated pool, holding the rows of one guild. */
 	static async attach(sql: SQL, guildId: string): Promise<PgAgentStore> {
 		const store = new PgAgentStore(sql, guildId);
-		await store.#reload();
+		// `Roundtable.check()` has no database to read the rows from: the store starts empty.
+		if (!isCheckDatabase(sql)) await store.#reload();
 		return store;
 	}
 

package/src/core/builtin/discord.ts

@@ -68,6 +68,8 @@ export interface DiscordOptions {
 	channelContext?: ChannelContextOptions | false;
 	/** The divider posted in a server channel when its conversation starts over; `false` posts none. Default: a short English divider. */
 	freshMarker?: string | false;
+	/** What the model is told about how replies render in Discord; `false` tells it nothing. Default: Markdown renders, except tables. */
+	formatting?: string | false;
 	/**
 	 * How long a turn waits on its owner card before it goes on without the answer, leaving the
 	 * card open; a later answer starts a new turn. Default `CARD_GRACE_MS`, two minutes.
@@ -135,6 +137,9 @@ export function discordPlugin(options: DiscordOptions): RoundtablePlugin {
 				...(options.freshMarker === undefined
 					? {}
 					: { freshMarker: options.freshMarker }),
+				...(options.formatting === undefined
+					? {}
+					: { formatting: options.formatting }),
 			});
 			surface = connected;
 			// Every owner may use the owner's commands, by the identity service; the primary owner always.

package/src/core/config/adapters.ts

@@ -57,6 +57,13 @@ export interface DiscordConfig {
 	 * never in a direct message. Default `─── new conversation ───`; `false` posts none.
 	 */
 	freshMarker?: string | false;
+	/**
+	 * What the model is told, English, about how a reply renders in Discord, appended to the system
+	 * prompt of every turn that replies there, after the persona. The default says Markdown
+	 * renders except tables, so the model writes bullet lists or `key: value` lines instead. A text
+	 * replaces it; `false` tells the model nothing.
+	 */
+	formatting?: string | false;
 	/**
 	 * Seconds a turn waits on an owner card (an approval or an `ask_user` question) before it goes
 	 * on without the answer; the card stays open, and answering it later starts a new turn with
@@ -94,6 +101,7 @@ export interface ResolvedDiscord {
 	/** As configured: `{}` when left out, so the defaults apply, or `false`. */
 	channelContext: NonNullable<DiscordConfig["channelContext"]>;
 	freshMarker?: string | false;
+	formatting?: string | false;
 	cardGraceSeconds: number;
 	/** As configured: `{}` when left out, so the defaults apply, or `false`. */
 	cardCopies: NonNullable<DiscordConfig["cardCopies"]> | false;
@@ -125,6 +133,9 @@ export function resolvedDiscord(
 		...(discord.freshMarker === undefined
 			? {}
 			: { freshMarker: discord.freshMarker }),
+		...(discord.formatting === undefined
+			? {}
+			: { formatting: discord.formatting }),
 		cardGraceSeconds: discord.cardGraceSeconds ?? 120,
 		cardCopies: discord.cardCopies ?? {},
 		...(discord.attachmentDownload === undefined
@@ -167,6 +178,7 @@ export const discordShape = shape({
 	agentSpeakers: optional(oneOf<"everyone" | "owners">("everyone", "owners")),
 	channelContext: optional(orOff(channelContextShape)),
 	freshMarker: optional(orOff(text)),
+	formatting: optional(orOff(text)),
 	cardGraceSeconds: optional(integer(1, 86_400)),
 	cardCopies: optional(
 		orOff(

package/src/core/contract/runtime.ts

@@ -147,6 +147,13 @@ export interface RuntimeDeps {
 		conversation: ChannelKey,
 		scope?: PromptScope | Speaker,
 	): Prompts | undefined;
+	/**
+	 * The formatting guidance of the chat surface that serves a channel, as `ChatSurface.formatting`
+	 * says; undefined when none serves it or it gives none. A runtime that builds its own system
+	 * prompt appends it after the persona, for the channel a turn replies in. Optional so a host
+	 * that predates 0.17 still type-checks.
+	 */
+	formatting?(channel: ChannelKey): string | undefined;
 	/**
 	 * The agent server's per-agent settings, for agent turns. The runtime is built before the agent
 	 * server, so read this when a turn runs, not in the factory; it stays undefined on a host without

package/src/core/contract/surface.ts

@@ -43,6 +43,13 @@ export interface ChatSurface {
 	readonly surface: string;
 	/** Explicit opt-in to delivering OutboundReply.files; absent or false refuses turn attachments. */
 	readonly supportsFiles?: boolean;
+	/**
+	 * Short English guidance on how a reply renders here, such as "no Markdown tables", which the
+	 * runtime appends to the system prompt of every turn that replies on this surface, after the
+	 * persona. It is model-facing text, so it is not a message-catalog string. Absent = nothing is
+	 * appended; a turn whose channel has no surface gets none either.
+	 */
+	readonly formatting?: string;
 	/**
 	 * Connects and delivers every incoming message; the host passes its conversation router. A
 	 * message whose channel key has another prefix is logged and dropped.

package/src/core/db/check-database.ts

@@ -0,0 +1,39 @@
+import type { SQL } from "bun";
+
+const REFUSAL =
+	"the database was queried during setup, which `Roundtable.check()` does not migrate or connect. Open stores lazily, and query from a service's start or from a handler";
+
+function refuse(): never {
+	throw new Error(REFUSAL);
+}
+
+/**
+ * The database a plugin's setup sees under `check()`: a pool that exists, so a store can attach to
+ * it, but that refuses every query, transaction and connection. A refusal reaches the plugin as an
+ * ordinary setup error, which the host words with the plugin's name.
+ */
+export function checkDatabase(): SQL {
+	// SAFETY: the stand-in answers the members of SQL a plugin could reach during setup, all by refusing.
+	const stand = new Proxy(refuse, {
+		apply: refuse,
+		// Not awaitable and no other symbol, so returning it from an async setup or logging it is harmless.
+		get: (_target, property) =>
+			property === STAND_IN
+				? true
+				: typeof property === "symbol" || property === "then"
+					? undefined
+					: refuse,
+	}) as unknown as SQL;
+	return stand;
+}
+
+const STAND_IN = Symbol("roundtable.checkDatabase");
+
+/**
+ * Whether `sql` is the stand-in `check()` hands the plugins. The built-in plugins whose setup would
+ * otherwise write to the database, such as the identity plugin's configuration sync, skip that
+ * write under it: `check()` proves the registration, not the data.
+ */
+export function isCheckDatabase(sql: SQL): boolean {
+	return (sql as unknown as Record<symbol, unknown>)[STAND_IN] === true;
+}

package/src/core/define-roundtable.ts

@@ -173,6 +173,9 @@ function discordAssembly(
 			...(discord.freshMarker === undefined
 				? {}
 				: { freshMarker: discord.freshMarker }),
+			...(discord.formatting === undefined
+				? {}
+				: { formatting: discord.formatting }),
 			cardGraceMs: discord.cardGraceSeconds * 1_000,
 			cardCopies: discord.cardCopies,
 		}),

package/src/core/discord/discord-surface.ts

@@ -34,6 +34,7 @@ import type { ChannelExecutor } from "./channel-operations.ts";
 import type { ComposedCommands } from "./compose-commands.ts";
 import type { ChannelInfo, DiscordConnection } from "./connection.ts";
 import { DiscordThreadHost } from "./dispatch-thread-host.ts";
+import { DISCORD_FORMATTING, pickFormatting } from "./formatting.ts";
 import { DEFAULT_FRESH_MARKER, postFreshMarker } from "./fresh-marker.ts";
 import { lateAnswerMessage, toInbound } from "./inbound-message.ts";
 import type { CardChannel, LateTurn } from "./owner-cards.ts";
@@ -59,6 +60,8 @@ export interface DiscordSurfaceOptions {
 	logger: Logger;
 	/** The divider posted in a server channel when its conversation starts over; `false` posts none. Default: `DEFAULT_FRESH_MARKER`. */
 	freshMarker?: string | false;
+	/** What the model is told about how replies render here; `false` tells it nothing. Default: `DISCORD_FORMATTING`. */
+	formatting?: string | false;
 }
 
 /**
@@ -72,6 +75,7 @@ export class DiscordSurface
 {
 	readonly surface = "discord";
 	readonly supportsFiles = true;
+	readonly formatting: string | undefined;
 	readonly #options: DiscordSurfaceOptions;
 	readonly #client = new Client({
 		intents: [
@@ -89,6 +93,7 @@ export class DiscordSurface
 
 	constructor(options: DiscordSurfaceOptions) {
 		this.#options = options;
+		this.formatting = pickFormatting(options.formatting, DISCORD_FORMATTING);
 	}
 
 	/** Slash commands and the modules that answer them; the commands are registered globally at startup. */

package/src/core/discord/formatting.ts

@@ -0,0 +1,20 @@
+/**
+ * What the model is told about Discord's rendering, as the surface's `formatting`. English: it is
+ * model-facing text, not a message-catalog string.
+ */
+export const DISCORD_FORMATTING =
+	"Reply formatting (Discord): Markdown renders, except tables, which show as raw | pipes, so use bullet lists or `key: value` lines instead of tables. Headings, bold, italics, lists, quotes, inline code, fenced code blocks and -# small text all work. A reply over 2,000 characters is split into several messages, so keep answers compact.";
+
+/** The guidance a surface option picks: the built-in when absent, none for `false`, else the override. */
+export function pickFormatting(
+	option: string | false | undefined,
+	builtin: string,
+): string | undefined {
+	if (option === false) return undefined;
+	if (option === undefined) return builtin;
+	if (option.trim() === "")
+		throw new Error(
+			"formatting is empty; write the guidance, or false to give the model none",
+		);
+	return option;
+}