@softov/ahpc 0.1.0

package/dist/src/control.js

@@ -0,0 +1,2241 @@
+import { createBag, serviceKey } from '@textui/core';
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { confirm } from '@textui/widgets';
+import { findBlocks, toBlocks } from './blocks.js';
+import { operate } from './ahp/operate.js';
+import { createTerminals } from './terminal.js';
+import { SessionFlag } from './ahp/types.js';
+import { valueIcon } from './view/icons.js';
+import { ARCHIVED, BOOD_FLOAT, CAN_ADD_CHAT, CAN_FORK, CAN_SIDE_CHAT, CHAT_URI, CHATS, CUSTOMIZATIONS, CURSOR, DRAFT, EXPANDED, FILTER, FIND, FINDING, FIND_AT, HAS_CHATS, HOST, HOST_ERROR, INPUT, MODEL, MODEL_CONFIG, OPEN_TERMINAL, AUTOMATIONS, AUTOMATION_ROW, CHANGES as CHANGES_AT_PATH, CHANGE_AT, CHANGE_ROW, CHANGE_SCOPES, FILES_AT, FILES_OPEN, OPEN, OPEN_FILE, PROVIDER, MARKDOWN, QUEUE, RUNNING, SCREEN, SELECTED, SETTINGS, SIDEBAR, SPLIT_AT, SPLIT_DEFAULT, TURNS, WORKSPACE, applyEvent, inputRefused, pendingInput, queue, reportHostError, sendingInput, sessions, turns, writeSessions, writeStatus, } from './state.js';
+export const CONTROLLER = serviceKey('chat.controller');
+/** The command that asks about one config key. Registered when a host offers it. */
+/**
+ * How long to wait before telling the host what is being typed.
+ *
+ * Long enough that a sentence is one dispatch rather than forty, short enough
+ * that leaving the screen mid-word does not lose the word.
+ */
+const DRAFT_DEBOUNCE_MS = 600;
+export const settingCommand = (key) => `compose.set.${key}`;
+/** One per property of the chosen model's own schema. */
+export const modelCommand = (key) => `compose.model.${key}`;
+/**
+ * The two focus scopes, and why single-letter keys need them.
+ *
+ * The runtime already offers a key to the focused node before any keybinding,
+ * so `q` typed into the composer is a letter and not a quit. What a scope adds
+ * is *where a key exists at all*: `d` disposes a session on the catalogue and
+ * means nothing in a conversation, and a binding that exists on both screens
+ * is one that fires on the wrong one.
+ *
+ * A scope is active while the component that declares it is mounted, so the
+ * screens are what turn these on and off.
+ */
+export const SESSIONS_SCOPE = 'chat.sessions';
+export const CHAT_SCOPE = 'chat.conversation';
+export const SKILLS_SCOPE = 'chat.skills';
+export const MCP_SCOPE = 'chat.mcp';
+export const CHANGES_SCOPE = 'chat.changes';
+export const AUTOMATIONS_SCOPE = 'chat.automations';
+export function createController(app, host, bindings) {
+    const bag = createBag();
+    // The client's own copy of the conversation, kept so a delta can be applied
+    // to the part it names rather than the store being read back and rewritten.
+    let model = [];
+    let subscription = null;
+    app.store.set(HOST, { id: host.id, url: host.url, state: host.state() });
+    app.store.set(FILTER, '');
+    app.store.set(ARCHIVED, false);
+    app.store.set(EXPANDED, {});
+    app.store.set(QUEUE, []);
+    app.store.set(DRAFT, '');
+    // What the first message will be sent as, before there is a session to ask.
+    app.store.set(PROVIDER, 'claude');
+    app.store.set(MODEL, '');
+    app.store.set(SETTINGS, {});
+    /**
+     * What to do when the host says no.
+     *
+     * Everything below is either fire-and-forget or driven from an effect, so a
+     * rejection has nowhere to be caught by the caller - and an unhandled
+     * rejection ends the process, from a terminal sitting in its alternate
+     * screen. A refusal is information: it goes where the screens can read it.
+     */
+    /**
+     * One command per question the host says it will answer.
+     *
+     * Registered rather than written, because the questions are the harness's
+     * and not this client's: `permissionMode` is what the fixture calls its key
+     * and a real host's are `isolation`, `autoApprove` and `mode`. A command
+     * naming a key works against one host, so nothing here names one - the
+     * schema arrives, and the palette and the control row have it.
+     *
+     * Late binding is the whole point: a harness that grows a new setting grows
+     * a new chip and a new palette entry, and this file does not change.
+     */
+    const offered = new Map();
+    /** The same, for the chosen model's own schema, which is a separate document. */
+    const modelOffered = new Map();
+    const unicode = app.capabilities.unicode;
+    /**
+     * One command per question the chosen model asks.
+     *
+     * The protocol says a client presents a model's `configSchema` as a form and
+     * returns the answers in `ModelSelection.config`, so these write to
+     * `MODEL_CONFIG` and ride out on the next message rather than being
+     * dispatched at the session. The two documents are kept apart on purpose:
+     * the session's schema is the host's and outlives any model, this one goes
+     * when the model does.
+     */
+    const offerModel = (properties) => {
+        for (const [id, disposable] of modelOffered) {
+            disposable.dispose();
+            modelOffered.delete(id);
+        }
+        for (const property of properties) {
+            if (property.values.length === 0)
+                continue;
+            const id = modelCommand(property.key);
+            modelOffered.set(id, app.commands.register({
+                id,
+                title: property.title,
+                category: 'Compose',
+                slots: ['palette'],
+                args: [{
+                        name: 'value',
+                        type: 'string',
+                        required: true,
+                        description: property.description ?? `Choose ${property.title.toLowerCase()}`,
+                        get default() {
+                            const answers = app.store.get(MODEL_CONFIG) ?? {};
+                            // What the host said it opens with, where nothing has been chosen.
+                            return answers[property.key] ?? property.default;
+                        },
+                        ...(property.values.some((value) => value.description)
+                            ? { descriptions: 'below' }
+                            : {}),
+                        choices: () => property.values.map((value) => ({
+                            value: value.value,
+                            label: value.label,
+                            ...(value.description ? { description: value.description } : {}),
+                        })),
+                    }],
+                run: (args) => {
+                    const chosen = property.values.find((value) => value.value === String(args.value));
+                    if (!chosen)
+                        return;
+                    const answers = app.store.get(MODEL_CONFIG) ?? {};
+                    app.store.set(MODEL_CONFIG, { ...answers, [property.key]: chosen.value });
+                },
+            }));
+        }
+    };
+    const offer = (config, uri) => {
+        const keep = new Set();
+        for (const property of config.properties) {
+            // Nothing to choose from is nothing to ask: a host's `permissions` key
+            // is an object the agent maintains, not a question with answers. Unless
+            // the host said to ask - `enumDynamic` is a schema whose values are a
+            // query, and an empty `enum` beside it means "not listed here", not
+            // "none".
+            if (property.values.length === 0 && property.enumDynamic !== true)
+                continue;
+            // A session that exists can only be changed where the host says so, and
+            // offering the rest produces a refusal instead of an edit.
+            if (uri && !property.sessionMutable)
+                continue;
+            const id = settingCommand(property.key);
+            keep.add(id);
+            offered.get(id)?.dispose();
+            // Whether the values are worth a mark at all. Five approval modes named
+            // in the same two words need one; a list of branch names does not, and a
+            // column of identical dots beside them is noise with a shape.
+            const marked = property.values.some((value) => valueIcon(unicode, value.value, value.label));
+            offered.set(id, app.commands.register({
+                id,
+                title: property.title,
+                category: 'Compose',
+                slots: ['palette'],
+                args: [{
+                        name: 'value',
+                        type: 'string',
+                        required: true,
+                        description: property.description ?? `Choose ${property.title.toLowerCase()}`,
+                        /*
+                         * What it is set to now, so the picker opens on that row.
+                         *
+                         * Read through a getter rather than captured: `offer` runs when the
+                         * schema arrives and the value changes every time one of these is
+                         * answered, so a value read at registration time is the answer that
+                         * was in force when the host first replied.
+                         */
+                        get default() {
+                            const values = app.store.get(SETTINGS) ?? {};
+                            return values[property.key];
+                        },
+                        // The host's own words, all three of them. "Auto Mode" and "Plan
+                        // Mode" are two words apart and mean entirely different things; the
+                        // sentence under each is what tells them apart, and it is the
+                        // difference between picking and guessing.
+                        //
+                        // Which is why the sentence gets a line of its own as soon as one of
+                        // the values has one. Beside the label it shares the width with it,
+                        // and a column of "Every tool call is c…" / "File edits run; com…"
+                        // truncates away the exact part the reader is choosing on.
+                        ...(property.values.some((value) => value.description)
+                            ? { descriptions: 'below' }
+                            : {}),
+                        /*
+                         * Asked for where the host said to ask, listed where it did not.
+                         *
+                         * `enumDynamic` means the values are a query rather than a schema -
+                         * a branch list on a large repository is exactly that - so this
+                         * calls `sessionConfigCompletions` and falls back to whatever the
+                         * schema did carry if the host will not answer.
+                         */
+                        choices: property.enumDynamic === true && host.configCompletions
+                            ? async () => {
+                                try {
+                                    const found = await host.configCompletions?.({
+                                        property: property.key,
+                                        provider: app.store.get(PROVIDER) ?? '',
+                                        ...(app.store.get(WORKSPACE) ? { workingDirectory: app.store.get(WORKSPACE) } : {}),
+                                        values: app.store.get(SETTINGS) ?? {},
+                                    });
+                                    return (found ?? []).map((one) => ({
+                                        value: one.value,
+                                        label: one.label,
+                                        ...(one.description ? { description: one.description } : {}),
+                                    }));
+                                }
+                                catch {
+                                    return property.values.map((value) => ({ value: value.value, label: value.label }));
+                                }
+                            }
+                            : () => property.values.map((value) => ({
+                                value: value.value,
+                                label: value.label,
+                                ...(marked ? { icon: valueIcon(unicode, value.value, value.label, { fallback: true }) } : {}),
+                                ...(value.description ? { description: value.description } : {}),
+                            })),
+                    }],
+                run: (args) => {
+                    // A dynamic property's values were never in the schema, so there is
+                    // nothing here to check one against: what the host offered is what
+                    // came back, and rejecting it would reject every answer.
+                    const value = String(args.value);
+                    const chosen = property.enumDynamic === true
+                        ? { value }
+                        : property.values.find((one) => one.value === value);
+                    if (!chosen)
+                        return;
+                    const current = app.store.get(SETTINGS) ?? {};
+                    app.store.set(SETTINGS, { ...current, [property.key]: chosen.value });
+                    const open = app.store.get(OPEN);
+                    // One key at a time: the action merges, so sending the object
+                    // writes back whatever this client happened to be holding.
+                    if (open)
+                        host.setConfig(open, property.key, chosen.value);
+                },
+            }));
+        }
+        // A harness the composer just switched to does not answer the last one's
+        // questions, and a chip pointing at a command nobody unregistered is a
+        // panel offering another harness's values.
+        for (const [id, disposable] of offered) {
+            if (keep.has(id))
+                continue;
+            disposable.dispose();
+            offered.delete(id);
+        }
+    };
+    bag.add({
+        dispose: () => {
+            for (const disposable of offered.values())
+                disposable.dispose();
+            offered.clear();
+        },
+    });
+    const failed = (error) => {
+        const rpc = error;
+        const message = rpc?.message ?? String(error);
+        reportHostError(app.store, typeof rpc?.code === 'number' ? `${message} (${rpc.code})` : message);
+    };
+    /**
+     * Read the catalogue again, at most once per turn of the loop.
+     *
+     * The host says "something moved" per action, and a turn finishing is
+     * several of them - so the unguarded version is one `listSessions` per
+     * delta. Coalescing makes a burst one read, and the read is what the list
+     * is drawn from either way.
+     */
+    let pending = null;
+    const refreshSoon = () => {
+        if (pending)
+            return;
+        pending = setTimeout(() => { pending = null; void reread(); }, 120);
+        // Nothing here should hold a process open: this is a repaint, not work.
+        pending.unref?.();
+    };
+    bag.add({ dispose: () => { if (pending)
+            clearTimeout(pending); pending = null; } });
+    /**
+     * Read the catalogue, and say nothing about anything else.
+     *
+     * `refresh` clears the last refusal, because a person pressing `r` is asking
+     * whether the host is answering again and a fresh list is the answer. This
+     * one is not that: it runs whenever the host says something moved, and a
+     * catalogue that answered says nothing about a session channel that refused
+     * - so clearing it here wiped "Authentication is required" off the status
+     * bar the moment any other session ticked.
+     */
+    const reread = async () => {
+        try {
+            writeSessions(app.store, await host.listSessions());
+        }
+        catch (error) {
+            failed(error);
+        }
+    };
+    /**
+     * What each provider says it can do, by provider id.
+     *
+     * Asked once at boot rather than when a palette happens to open: the chat
+     * commands are gated on it, and a gate that answers "no" until somebody
+     * opens an unrelated picker is a command missing for no visible reason.
+     */
+    const capable = new Map();
+    /**
+     * Whether one session's agent can hold another chat.
+     *
+     * Read from the row's own provider rather than the composer's: a client can
+     * have several hosts' sessions in one list, and only some of their agents
+     * can hold more than one.
+     */
+    const canAddChat = (uri) => {
+        const found = sessions(app.store).find((row) => row.resource === uri)?.provider;
+        return found !== undefined && capable.get(found) === true;
+    };
+    /** The two chat sources, each gated on the agent advertising that one. */
+    const sources = new Map();
+    const canSource = (uri, kind) => {
+        const found = sessions(app.store).find((row) => row.resource === uri)?.provider;
+        return found !== undefined && sources.get(found)?.[kind] === true;
+    };
+    void host.agents().then((found) => {
+        for (const entry of found)
+            capable.set(entry.provider, entry.multipleChats === true);
+        for (const entry of found)
+            sources.set(entry.provider, entry.chatSources ?? {});
+        // A session may already be open by the time this lands.
+        const uri = app.store.get(OPEN);
+        if (uri)
+            app.store.set(CAN_ADD_CHAT, canAddChat(uri));
+        if (uri) {
+            app.store.set(CAN_FORK, canSource(uri, 'fork'));
+            app.store.set(CAN_SIDE_CHAT, canSource(uri, 'sideChat'));
+        }
+    }).catch(() => undefined);
+    const terminals = createTerminals(app, host, failed);
+    /**
+     * The draft, on its way to the host, debounced.
+     *
+     * `chat-channel.md`: clients SHOULD debounce and MAY sync only at
+     * convenient points - eager syncing is explicitly not required. A dispatch
+     * per keystroke would be one round trip per character and a snapshot back
+     * for each.
+     */
+    let draftTimer;
+    bag.add({ dispose: () => clearTimeout(draftTimer) });
+    const controller = {
+        offerModel,
+        draft(text) {
+            const uri = app.store.get(OPEN);
+            if (!uri)
+                return;
+            clearTimeout(draftTimer);
+            draftTimer = setTimeout(() => { host.setDraft(uri, text); }, DRAFT_DEBOUNCE_MS);
+        },
+        async refresh() {
+            try {
+                writeSessions(app.store, await host.listSessions());
+                app.store.set(HOST_ERROR, null);
+            }
+            catch (error) {
+                failed(error);
+            }
+        },
+        report: failed,
+        /**
+         * Read a different chat in the session already open.
+         *
+         * A whole re-subscribe rather than a swap: the transcript, the queue and
+         * what is waiting all belong to the chat, so keeping any of them across
+         * the change would show one conversation's state under another's name.
+         */
+        terminals,
+        completions: (channel, text, offset) => host.completions({
+            channel,
+            text,
+            ...(offset !== undefined ? { offset } : {}),
+        }),
+        openChat(chat) {
+            const uri = app.store.get(OPEN);
+            if (!uri || app.store.get(CHAT_URI) === chat)
+                return;
+            subscription?.close();
+            model = [];
+            app.store.set(TURNS, []);
+            app.store.set(INPUT, null);
+            app.store.set(QUEUE, []);
+            app.store.set(CHAT_URI, chat);
+            subscription = host.subscribe(uri, (event) => {
+                model = applyEvent(app.store, event, model);
+                if (event.type === 'status')
+                    refreshSoon();
+            }, chat);
+        },
+        async createChat(first, source) {
+            const uri = app.store.get(OPEN);
+            if (!uri)
+                return;
+            try {
+                const chat = await host.createChat(uri, first, source);
+                controller.openChat(chat);
+            }
+            catch (error) {
+                failed(error);
+            }
+        },
+        async disposeChat(chat) {
+            try {
+                await host.disposeChat(chat);
+            }
+            catch (error) {
+                failed(error);
+                return;
+            }
+            // Whatever is left. The host moves its own default; this client only
+            // has to stop reading a chat that is gone.
+            const left = (app.store.get(CHATS) ?? [])
+                .map((entry) => entry.resource)
+                .filter((resource) => resource !== chat);
+            const next = left[0];
+            if (next)
+                controller.openChat(next);
+        },
+        open(uri) {
+            // Closing drops this consumer only. Unsubscribing the channel to shed a
+            // duplicate is what silently kills the stream everything else reads.
+            subscription?.close();
+            model = [];
+            // Reading it is what makes it read, and the host tells every other
+            // client so. Nobody marks their own mail by hand.
+            host.setRead(uri, true);
+            app.store.set(OPEN, uri);
+            app.store.set(TURNS, []);
+            app.store.set(INPUT, null);
+            // Null rather than empty: the skills are this session's, and two
+            // sessions on the same host in different directories are handed
+            // different ones. An empty list would say "the host gave it none",
+            // which is an answer, and this is "nobody has asked yet".
+            app.store.set(CUSTOMIZATIONS, null);
+            app.store.set(CHATS, []);
+            app.store.set(HAS_CHATS, false);
+            app.store.set(CAN_ADD_CHAT, canAddChat(uri));
+            app.store.set(CAN_FORK, canSource(uri, 'fork'));
+            app.store.set(CAN_SIDE_CHAT, canSource(uri, 'sideChat'));
+            app.store.set(OPEN_FILE, null);
+            subscription = host.subscribe(uri, (event) => {
+                model = applyEvent(app.store, event, model);
+                // The open session's own status still refreshes the list here: the
+                // catalogue watch below covers what the *host* says moved, and this
+                // covers what this client is watching happen.
+                if (event.type === 'status')
+                    refreshSoon();
+            });
+            // The composer's row is about the next message, so on an open session it
+            // has to describe *that* session: its harness, its workspace, the
+            // permission mode in force and what its last turn ran on. Left alone it
+            // would keep describing whatever was chosen on the new-session screen,
+            // which is a row of confident, wrong answers.
+            const summary = sessions(app.store).find((found) => found.resource === uri);
+            if (summary) {
+                app.store.set(PROVIDER, summary.provider);
+                app.store.set(WORKSPACE, (summary.workingDirectories[0] ?? '').replace(/^file:\/\//, ''));
+            }
+            app.store.set(CHAT_URI, null);
+            void host.detail(uri).then((detail) => {
+                if (app.store.get(OPEN) !== uri)
+                    return;
+                app.store.set(SETTINGS, detail.config.values);
+                app.store.set(CHAT_URI, detail.chat);
+                // The id, which is what a turn rides on and what the picker matches
+                // against. The name beside it is the catalogue's, and resolving it is
+                // the chip's job rather than something to store a second copy of.
+                if (detail.model)
+                    app.store.set(MODEL, detail.model.id);
+                offer(detail.config, uri);
+            }).catch(failed);
+        },
+        close() {
+            subscription?.close();
+            subscription = null;
+            app.store.set(OPEN, null);
+            app.store.set(TURNS, []);
+            app.store.set(INPUT, null);
+            app.store.set(CUSTOMIZATIONS, null);
+            app.store.set(CHATS, []);
+            app.store.set(HAS_CHATS, false);
+            app.store.set(CAN_ADD_CHAT, false);
+            app.store.set(CAN_FORK, false);
+            app.store.set(CAN_SIDE_CHAT, false);
+            app.store.set(OPEN_FILE, null);
+            // Idle, because nothing is open. A status that outlived the conversation
+            // it described is a header saying "running" over an empty screen.
+            writeStatus(app.store, 1);
+        },
+        send(text) {
+            const uri = app.store.get(OPEN);
+            const trimmed = text.trim();
+            if (!uri || trimmed === '')
+                return;
+            /*
+             * The draft is cleared here and at the host, and the pending sync is
+             * dropped.
+             *
+             * `draft()` debounces, so at the moment a message is sent there is
+             * usually a timer holding the text that was just sent. Left to fire it
+             * tells the host that is the draft; the host stores it and echoes
+             * `chat/draftChanged` back, and the message reappears in the composer a
+             * moment after it was sent - which reads as the send having failed.
+             */
+            clearTimeout(draftTimer);
+            app.store.set(DRAFT, '');
+            host.setDraft(uri, '');
+            const history = app.store.get('$/chat/ui/history') ?? [];
+            app.store.set('$/chat/ui/history', [...history, trimmed]);
+            // The model rides on the turn, not on the session: AHP hangs it on the
+            // message, so the composer's choice is applied here rather than being
+            // set on the session once.
+            const chosen = app.store.get(MODEL);
+            // The model's own answers go with it, in `ModelSelection.config` - the
+            // field the schema says a client returns a `configSchema` form in.
+            const answers = app.store.get(MODEL_CONFIG) ?? {};
+            const selection = chosen
+                ? { id: chosen, ...(Object.keys(answers).length > 0 ? { config: answers } : {}) }
+                : undefined;
+            // A turn is already running: this is a queued message, not a second
+            // turn. Sending it anyway is how two turns end up interleaved in one
+            // chat, and the host is not the thing that stops you.
+            //
+            // Queued *on the host*, which is the whole difference between a queue
+            // and a list. Held here it was never sent - nothing in this client was
+            // watching for the turn to end, so a message typed while the agent was
+            // working sat under the transcript saying `queued` until the session was
+            // closed. The host starts the next turn from the head as soon as it goes
+            // idle, and every client watching this chat sees the same queue.
+            if (turns(app.store).some((turn) => turn.state === 'running')) {
+                host.queue(uri, trimmed, selection);
+                return;
+            }
+            host.say(uri, trimmed, selection);
+        },
+        unqueue(id) {
+            const uri = app.store.get(OPEN);
+            if (!uri)
+                return;
+            host.unqueue(uri, id);
+        },
+        stop() {
+            const uri = app.store.get(OPEN);
+            if (uri)
+                host.stopTurn(uri);
+        },
+        /*
+         * The three that answer the block, and the one thing they have in common.
+         *
+         * Each of them can decline to do anything at all - there is no session
+         * open, the block up is the other kind, a required question is unanswered
+         * - and returning on that quietly is how a button comes to do nothing
+         * when pressed. Every path out of here now says which one it took, on the
+         * row above the composer: gone to the host, or not going and why.
+         */
+        approve(optionId) {
+            const uri = app.store.get(OPEN);
+            const input = pendingInput(app.store);
+            if (!uri || input?.kind !== 'toolConfirmation') {
+                inputRefused(app.store, 'Nothing is waiting to be approved');
+                return;
+            }
+            // The option's label, not its id: a live host's option ids are whole
+            // sentences with punctuation in them, and one of those in a status row
+            // is the row's whole width spent on something nobody reads.
+            const chosen = input.call.options?.find((option) => option.id === optionId);
+            sendingInput(app.store, chosen ? `Approving - ${chosen.label}...` : 'Approving...');
+            host.confirmToolCall(uri, input.call.id, true, optionId);
+        },
+        deny() {
+            const uri = app.store.get(OPEN);
+            const input = pendingInput(app.store);
+            if (!uri || input?.kind !== 'toolConfirmation') {
+                inputRefused(app.store, 'Nothing is waiting to be denied');
+                return;
+            }
+            sendingInput(app.store, 'Denying...');
+            host.confirmToolCall(uri, input.call.id, false);
+        },
+        answer(answers, accepted = true) {
+            const uri = app.store.get(OPEN);
+            const input = pendingInput(app.store);
+            if (!uri || input?.kind !== 'chatInput') {
+                inputRefused(app.store, 'No question is waiting to be answered');
+                return;
+            }
+            // An accept with no answers resumes the agent on the answers it already
+            // had, which for a question it has just asked is none.
+            const missing = input.questions.filter((q) => q.required && !answers[q.id]);
+            if (accepted && missing.length > 0) {
+                inputRefused(app.store, `${String(missing.length)} still to answer`);
+                return;
+            }
+            sendingInput(app.store, accepted ? 'Sending your answer...' : 'Declining...');
+            host.completeInput(uri, input.id, accepted, answers);
+        },
+        setArchived(uri, archived) {
+            host.setArchived(uri, archived);
+            void controller.refresh();
+        },
+        setRead(uri, read) {
+            host.setRead(uri, read);
+            void controller.refresh();
+        },
+        async disposeSession(uri) {
+            try {
+                await host.disposeSession(uri);
+            }
+            catch (error) {
+                failed(error);
+            }
+            if (app.store.get(OPEN) === uri)
+                controller.close();
+            await controller.refresh();
+        },
+        async create({ provider, workingDirectory, first }) {
+            // Not caught here: the caller is a screen that navigates on success, and
+            // navigating into a session the host refused to create is worse than the
+            // failure. It catches, and reports through `report`.
+            // What the control row was set to rides on the creation. Most of what a
+            // schema offers is not `sessionMutable`, so a session created without it
+            // is one that can never be told.
+            const config = app.store.get(SETTINGS) ?? {};
+            const uri = await host.createSession({
+                provider,
+                ...(workingDirectory ? { workingDirectory } : {}),
+                ...(Object.keys(config).length > 0 ? { config } : {}),
+            });
+            await controller.refresh();
+            controller.open(uri);
+            // The provider is lazy: a session sits in `creating` and emits nothing
+            // until there is a turn to run, so waiting for `ready` before the first
+            // dispatch is a deadlock - the dispatch is what causes it.
+            if (first)
+                controller.send(first);
+            return uri;
+        },
+        agents: () => host.agents(),
+        detail: (uri) => host.detail(uri),
+        config: (uri) => host.config(uri),
+        customizations: (uri) => host.customizations(uri),
+        harnessCommands: () => host.harnessCommands(),
+        setCustomizationEnabled: (uri, id, enabled) => host.setCustomizationEnabled(uri, id, enabled),
+        content: (ref) => host.content(ref),
+        loadOlderTurns: (uri) => host.loadOlderTurns(uri),
+        files: async (uri) => (await host.resourceList?.(uri)) ?? [],
+        /*
+         * Be told when a directory changes, instead of asking again.
+         *
+         * `resource-watch-channel.md` is explicit that there is no dispose
+         * command: releasing the last subscriber is what makes the host let the
+         * watcher go, so the returned handle is the whole of closing one. A host
+         * that will not serve a watch is not a failure - it answers `-32601` or
+         * refuses with `-32009`, and the screen goes on reading when it opens.
+         */
+        watchFiles: async (uri, changed) => {
+            if (!host.watchResource)
+                return { close: () => undefined };
+            try {
+                return await host.watchResource(uri, changed, { recursive: false });
+            }
+            catch {
+                return { close: () => undefined };
+            }
+        },
+        file: async (uri) => {
+            if (!host.resourceRead)
+                throw new Error('This host serves no files.');
+            return await host.resourceRead(uri);
+        },
+        automations: async () => {
+            if (!host.automations)
+                throw new Error('This host serves no automations.');
+            return await host.automations();
+        },
+        onAutomations: (observer) => host.onAutomations?.(observer) ?? { close: () => { } },
+        createAutomation: async (definition) => {
+            if (!host.createAutomation)
+                throw new Error('This host serves no automations.');
+            return await host.createAutomation(definition);
+        },
+        runAutomation: async (uri) => { await host.runAutomation?.(uri); },
+        setAutomationEnabled: async (uri, enabled) => { await host.setAutomationEnabled?.(uri, enabled); },
+        removeAutomation: async (uri) => { await host.removeAutomation?.(uri); },
+        changesets: async (uri) => (await host.changesets?.(uri)) ?? [],
+        changesAt: (uri, changeset) => host.changes(uri, changeset),
+        review: (changeset, files, isReviewed) => { host.review?.(changeset, files, isReviewed); },
+        async settings() {
+            const uri = app.store.get(OPEN) ?? null;
+            const config = uri
+                ? await host.config(uri)
+                : await host.resolveConfig({
+                    provider: app.store.get(PROVIDER) ?? 'claude',
+                    ...(app.store.get(WORKSPACE) ? { workingDirectory: app.store.get(WORKSPACE) } : {}),
+                    values: app.store.get(SETTINGS) ?? {},
+                });
+            // The host had the last word: `resolveSessionConfig` echoes what it was
+            // given with its own defaults filled in, so this is what is in force
+            // rather than what was asked for.
+            app.store.set(SETTINGS, config.values);
+            offer(config, uri);
+            return config;
+        },
+        setConfig: (uri, key, value) => host.setConfig(uri, key, value),
+        pump: () => host.pump?.() ?? false,
+    };
+    bag.add({ dispose: () => subscription?.close() });
+    // The terminal's subscription is the controller's, not a screen's - which is
+    // the point of the split, and means it has to be let go here.
+    bag.add({ dispose: () => { terminals.dispose(); } });
+    // What the host says about sessions this client is not watching: one
+    // appearing, one finishing, one starting to wait. Without it the catalogue
+    // is only ever as fresh as the last time somebody navigated to it.
+    const watching = host.onSessions(refreshSoon);
+    bag.add({ dispose: () => watching.close() });
+    for (const command of commands(app, controller, host))
+        bag.add(app.commands.register(command));
+    for (const binding of keys(bindings))
+        bag.add(app.keybindings.register(binding));
+    return Object.assign(controller, { dispose: () => bag.dispose() });
+}
+// ------------------------------------------------------------------- commands
+/** What to put back when a preview is abandoned. Only this knows what it changed. */
+const previous = { theme: null, shell: null };
+function commands(app, controller, 
+/*
+ * The connection, for the one command that needs it directly.
+ *
+ * Everything else here goes through the controller, and should: it is what
+ * keeps the commands from knowing there is a protocol. `changes.run` is the
+ * exception because `operate` is the negotiation - a refusal, a question,
+ * a retry - and wrapping that in a controller method would be hiding the
+ * question, which is the part a person has to answer.
+ */
+connection) {
+    const selected = () => app.store.get(SELECTED) ?? null;
+    const openUri = () => app.store.get(OPEN) ?? null;
+    /**
+     * Which session a command acts on.
+     *
+     * The one being read, when a conversation is on screen; otherwise the one
+     * selected in the catalogue. A command that only ever read the catalogue's
+     * selection would archive the row you opened this from rather than the
+     * session you are looking at.
+     */
+    const target = () => (app.screens.current()?.id === 'chat' ? openUri() : null) ?? selected() ?? openUri();
+    const running = () => turns(app.store).some((turn) => turn.state === 'running');
+    /**
+     * Move the transcript cursor to the match `by` away from the one it is on.
+     *
+     * The blocks are rebuilt here rather than read from the screen: a command
+     * has the store and nothing else, and the store holds the turns that the
+     * screen builds the same blocks from. Doing it once per keypress on a
+     * conversation is not the cost that matters.
+     */
+    const step = (by) => {
+        const query = app.store.get(FIND) ?? '';
+        const blocks = toBlocks(turns(app.store), app.store.get(QUEUE) ?? []);
+        const found = findBlocks(blocks, query);
+        if (found.length === 0)
+            return;
+        const from = Math.min(app.store.get(FIND_AT) ?? 0, found.length - 1);
+        const next = (from + by + found.length) % found.length;
+        app.store.set(FIND_AT, next);
+        app.store.set(CURSOR, found[next] ?? 0);
+    };
+    /**
+     * The catalogue, one screen above the composer.
+     *
+     * Reset-then-push rather than push: the catalogue is reachable from the
+     * composer, from a conversation and from the palette, and pushing from each
+     * of those would stack three copies of it that escape then walks back
+     * through one at a time.
+     */
+    const toSessions = () => {
+        app.screens.reset('new');
+        app.screens.push('sessions');
+        void controller.refresh();
+    };
+    /**
+     * What the host last said it offers.
+     *
+     * Filled by the `choices` functions, which the palette calls when it opens
+     * one of these - so the labels a person is choosing from and the list a
+     * choice is resolved against are always the same fetch.
+     */
+    const known = { agents: [] };
+    /*
+     * Asked once at boot, not only when a palette opens one of the pickers.
+     *
+     * The chat commands are gated on what the agent says it can do, and a gate
+     * that answers "no" until somebody happens to open an unrelated picker is a
+     * command that is missing for no reason anybody can see.
+     */
+    const provider = () => app.store.get(PROVIDER) ?? 'claude';
+    const agent = () => known.agents.find((found) => found.provider === provider());
+    const listAgents = async () => {
+        try {
+            known.agents = await controller.agents();
+        }
+        catch (error) {
+            controller.report(error);
+        }
+        // The provider id is what the command is answered with, and the harness's
+        // own description is what tells two of them apart - a person choosing
+        // between "Copilot" and "Claude" is choosing between two sentences.
+        return known.agents.map((found) => ({
+            value: found.provider,
+            label: found.displayName,
+            ...(found.description ? { description: found.description } : {}),
+        }));
+    };
+    const listModels = async () => {
+        if (known.agents.length === 0)
+            await listAgents();
+        // The id under the name: `claude-sonnet-4-5-20250929` is what a person
+        // recognises from a config file, and what they would search for.
+        return (agent()?.models ?? []).map((model) => ({
+            value: model.id,
+            label: model.displayName,
+            ...(model.displayName === model.id ? {} : { description: model.id }),
+        }));
+    };
+    return [
+        {
+            /**
+             * The creature, on and off, without editing a file.
+             *
+             * `boodFloat` in the config says what it is on startup; this says what
+             * it is now. A mascot that can only be turned off by quitting, editing
+             * JSON and starting again is one somebody keeps off.
+             */
+            id: 'bood.toggle',
+            title: 'Show the creature',
+            category: 'View',
+            slots: ['palette', 'config'],
+            run: () => {
+                const showing = app.store.get(BOOD_FLOAT) ?? false;
+                app.store.set(BOOD_FLOAT, !showing);
+            },
+        },
+        {
+            id: 'app.palette',
+            title: 'Command Palette',
+            category: 'Navigation',
+            slots: [],
+            run: () => {
+                app.layers.open({
+                    id: 'palette',
+                    layer: 'modal',
+                    scrim: true,
+                    trapFocus: true,
+                    dismissOnEscape: true,
+                    node: {
+                        component: 'CommandPalette',
+                        width: 62,
+                        commands: app.commands.list({ slot: 'palette', enabledOnly: true }),
+                        onClose: { handler: () => app.layers.close('palette') },
+                    },
+                });
+            },
+        },
+        /*
+         * The palette, with only the commands that configure this client in it.
+         *
+         * A slot rather than a screen of its own. Every one of these already
+         * answers a question about how the client looks or behaves, and a second
+         * place to ask them would be a second place to keep in step - so `config`
+         * is a second slot on the same commands, and this opens the same palette
+         * over a narrower list. A command joins it by naming the slot.
+         *
+         * `/config` finds it by id, the way every other client command in the
+         * slash menu is found.
+         */
+        {
+            id: 'app.config',
+            title: 'Configuration',
+            category: 'Navigation',
+            description: 'Theme, layout and the rest of what this client decides',
+            slots: ['palette'],
+            run: () => {
+                app.layers.open({
+                    id: 'palette',
+                    layer: 'modal',
+                    scrim: true,
+                    trapFocus: true,
+                    dismissOnEscape: true,
+                    node: {
+                        component: 'CommandPalette',
+                        width: 62,
+                        placeholder: 'Configure',
+                        commands: app.commands.list({ slot: 'config', enabledOnly: true }),
+                        onClose: { handler: () => app.layers.close('palette') },
+                    },
+                });
+            },
+        },
+        {
+            /*
+             * Every key that works right here, and what it does.
+             *
+             * The palette on `ctrl+p` is the list of *commands* and answers "what
+             * can I do"; this answers "what does this key do", which is the other
+             * question and the one a person asks with the keyboard in front of
+             * them. So it is the commands that have a chord, and only the ones
+             * whose `when` passes where the reader is standing - a keymap listing
+             * keys that do nothing here is a keymap that has to be second-guessed.
+             */
+            id: 'help.keys',
+            title: 'Keys',
+            category: 'Help',
+            description: 'Every key that does something here',
+            slots: ['palette'],
+            run: () => {
+                app.layers.open({
+                    id: 'palette',
+                    layer: 'modal',
+                    scrim: true,
+                    trapFocus: true,
+                    dismissOnEscape: true,
+                    node: {
+                        component: 'CommandPalette',
+                        width: 62,
+                        placeholder: 'Keys',
+                        commands: app.commands.list({ enabledOnly: true })
+                            .filter((command) => app.keybindings.forCommand(command.id).length > 0),
+                        onClose: { handler: () => app.layers.close('palette') },
+                    },
+                });
+            },
+        },
+        {
+            id: 'go.back',
+            title: 'Back',
+            category: 'Navigation',
+            description: 'Return to the previous screen',
+            slots: ['palette'],
+            run: () => {
+                // The composer is the root, so there is nothing under it to pop to -
+                // and escape on the one screen that has no way back would do nothing
+                // at all. From there it means "show me what already exists".
+                if (app.screens.current()?.id === 'new') {
+                    toSessions();
+                    return;
+                }
+                app.screens.pop();
+            },
+        },
+        {
+            /*
+             * The other half of what a host holds.
+             *
+             * Not gated on a session being open, unlike `go.changes`: an automation
+             * belongs to the host and outlives every session it starts, so it is
+             * reachable from anywhere - including from a client that has opened
+             * nothing at all.
+             */
+            id: 'go.automations',
+            title: 'What the host runs on its own',
+            category: 'Screens',
+            description: 'Show the automations',
+            slots: ['palette'],
+            run: () => { app.screens.push('automations'); },
+        },
+        {
+            id: 'automation.new',
+            title: 'Write a new automation',
+            category: 'Automations',
+            description: 'A session the host starts without being asked',
+            slots: ['palette'],
+            run: () => { app.screens.push('automation.new'); },
+        },
+        {
+            id: 'automation.run',
+            title: 'Run this automation now',
+            category: 'Automations',
+            description: 'Start a run, whatever the schedule says',
+            slots: ['palette'],
+            when: `${AUTOMATION_ROW}`,
+            run: async () => {
+                const uri = app.store.get(AUTOMATION_ROW) ?? '';
+                const found = (app.store.get(AUTOMATIONS) ?? []).find((one) => one.resource === uri);
+                // The host says which verbs it will accept, and a client that pressed
+                // one it did not offer would be asking to be refused. A switched-off
+                // automation offers no `run`.
+                if (!found?.operations.includes('run'))
+                    return;
+                try {
+                    await controller.runAutomation(uri);
+                }
+                catch (error) {
+                    controller.report(error);
+                }
+            },
+        },
+        {
+            id: 'automation.toggle',
+            title: 'Switch this automation on or off',
+            category: 'Automations',
+            description: 'Stop it firing, or let it fire again',
+            slots: ['palette'],
+            when: `${AUTOMATION_ROW}`,
+            run: async () => {
+                const uri = app.store.get(AUTOMATION_ROW) ?? '';
+                const found = (app.store.get(AUTOMATIONS) ?? []).find((one) => one.resource === uri);
+                if (!found?.operations.includes('update'))
+                    return;
+                try {
+                    await controller.setAutomationEnabled(uri, !found.enabled);
+                }
+                catch (error) {
+                    controller.report(error);
+                }
+            },
+        },
+        {
+            id: 'automation.remove',
+            title: 'Forget this automation',
+            category: 'Automations',
+            description: 'Delete it and everything it has done',
+            slots: ['palette'],
+            when: `${AUTOMATION_ROW}`,
+            run: async () => {
+                const uri = app.store.get(AUTOMATION_ROW) ?? '';
+                const found = (app.store.get(AUTOMATIONS) ?? []).find((one) => one.resource === uri);
+                if (!found?.operations.includes('remove'))
+                    return;
+                /*
+                 * Asked, because nothing gives it back.
+                 *
+                 * The protocol has no confirmation on this the way a changeset
+                 * operation carries one, so the question is this client's own - which
+                 * is the right way round: the host cannot know that a person is about
+                 * to lose the only copy of a schedule they wrote.
+                 */
+                const yes = await confirm(app.layers, {
+                    title: 'Forget this automation?',
+                    message: `${found.title} and its history go, and nothing here brings them back.`,
+                    confirmLabel: 'Forget it',
+                    cancelLabel: 'Keep it',
+                    tone: 'danger',
+                });
+                if (!yes)
+                    return;
+                try {
+                    await controller.removeAutomation(uri);
+                    app.store.set(AUTOMATION_ROW, '');
+                }
+                catch (error) {
+                    controller.report(error);
+                }
+            },
+        },
+        {
+            id: 'go.sessions',
+            title: 'Sessions',
+            category: 'Screens',
+            description: 'List all sessions',
+            slots: ['palette'],
+            run: () => toSessions(),
+        },
+        {
+            id: 'go.new',
+            title: 'New session',
+            category: 'Screens',
+            description: 'Start a new conversation',
+            slots: ['palette'],
+            run: () => { app.screens.reset('new'); app.focus.focus('chat.composer'); },
+        },
+        {
+            id: 'go.changes',
+            title: 'What this session changed',
+            category: 'Screens',
+            description: 'Show the files',
+            slots: ['palette'],
+            when: `${OPEN}`,
+            // Always the list, never wherever it was left. A screen that reopens on
+            // the one file somebody read an hour ago hides the other nineteen.
+            run: () => { app.store.set(OPEN_FILE, null); app.screens.push('changes'); },
+        },
+        {
+            /*
+             * The host's filesystem, which is where the project actually is.
+             *
+             * Beside the changes screen rather than under it: what changed and what
+             * is there are different questions, and a browser that only ever showed
+             * the changed files would be a changeset with a worse name.
+             */
+            id: 'go.files',
+            title: 'Browse the host\'s files',
+            category: 'Screens',
+            description: 'The project, as the host sees it',
+            slots: ['palette'],
+            when: `${OPEN}`,
+            run: () => {
+                // Always back at the top. A browser that reopens six directories deep
+                // is one nobody can tell from a broken one.
+                app.store.set(FILES_OPEN, '');
+                app.store.set(FILES_AT, '');
+                app.screens.push('files');
+            },
+        },
+        {
+            id: 'go.skills',
+            title: 'Skills and commands',
+            category: 'Screens',
+            description: 'What plugins and directories gave this session',
+            slots: ['palette'],
+            when: `${OPEN}`,
+            run: () => app.screens.push('skills'),
+        },
+        {
+            id: 'go.mcp',
+            title: 'MCP servers',
+            category: 'Screens',
+            description: 'Which servers this session has, and whether they answered',
+            slots: ['palette'],
+            when: `${OPEN}`,
+            run: () => app.screens.push('mcp'),
+        },
+        {
+            /*
+             * The next changeset this session offers.
+             *
+             * One key rather than a picker widget, because the list is short and
+             * every entry is a whole screen: cycling is what a person does to see
+             * the other three, and a menu to choose between four things you are
+             * about to look at anyway is a step in the way.
+             *
+             * Only the ones that are already URIs. A template with `{turnId}` still
+             * in it is a question about a turn, and there is nothing on this screen
+             * to answer it from - which is why the greyed rows say so rather than
+             * being silently dropped.
+             */
+            id: 'changes.scope',
+            title: 'Next changeset',
+            category: 'Changes',
+            run: () => {
+                const offered = (app.store.get(CHANGE_SCOPES) ?? [])
+                    .filter((scope) => scope.variables.length === 0);
+                if (offered.length === 0)
+                    return;
+                const at = app.store.get(CHANGE_AT) ?? '';
+                const seen = offered.findIndex((scope) => scope.uriTemplate === at);
+                const next = offered[(seen + 1) % offered.length];
+                app.store.set(CHANGE_AT, next?.uriTemplate ?? '');
+                // The open file belongs to the changeset it came from.
+                app.store.set(OPEN_FILE, null);
+            },
+        },
+        {
+            /*
+             * Ticking the row off, which is a note about reading rather than a change.
+             *
+             * The host keeps it and tells every client, so nothing is written here -
+             * what redraws the tick is the changeset coming back. That is the whole
+             * reason it is worth having: two people reading one diff can see which
+             * files the other has been through.
+             */
+            id: 'changes.review',
+            title: 'Mark this file read',
+            category: 'Changes',
+            run: () => {
+                const at = app.store.get(CHANGE_AT) ?? '';
+                const row = app.store.get(CHANGE_ROW) ?? '';
+                if (!at || !row)
+                    return;
+                const held = app.store.get(CHANGES_AT_PATH);
+                const file = held?.files.find((one) => one.uri === row);
+                controller.review(at, [row], file?.reviewed !== true);
+            },
+        },
+        {
+            /*
+             * Run the verb the changeset offers, asking first where the host said to.
+             *
+             * One command rather than one per verb, with the id as an argument, for
+             * the reason the config settings are registered the other way round: the
+             * *settings* are a fixed schema a host publishes once, and these change
+             * with every changeset - a command per operation would be registering
+             * and disposing three of them each time the scope moves.
+             *
+             * The confirmation is not optional. The protocol says a client MUST
+             * display it before invoking, and its presence is also how the host says
+             * the operation is destructive - so this is the screen's half of what
+             * `--yes` is in the shell.
+             */
+            id: 'changes.run',
+            title: 'Do something with these changes',
+            category: 'Changes',
+            when: `${SCREEN} == 'changes'`,
+            args: [{
+                    name: 'operation',
+                    type: 'string',
+                    required: true,
+                    description: 'Which of the verbs this changeset offers',
+                    // What the changeset advertises, now. An id that was not offered is
+                    // one the host will refuse, so there is nothing to gain by listing
+                    // more than it says.
+                    choices: () => {
+                        const held = app.store.get(CHANGES_AT_PATH);
+                        return (held?.operations ?? [])
+                            .filter((one) => one.status !== 'disabled')
+                            .map((one) => ({ value: one.id, label: one.label, description: one.description ?? '' }));
+                    },
+                }],
+            run: async (given) => {
+                const at = app.store.get(CHANGE_AT) ?? '';
+                const held = app.store.get(CHANGES_AT_PATH);
+                const wanted = String(given?.operation ?? '');
+                const operation = (held?.operations ?? []).find((one) => one.id === wanted);
+                if (!at || !operation)
+                    return;
+                const row = app.store.get(CHANGE_ROW) ?? '';
+                const onFile = !operation.scopes.includes('changeset');
+                if (onFile && !row)
+                    return;
+                if (operation.confirmation !== undefined) {
+                    const yes = await confirm(app.layers, {
+                        title: operation.label,
+                        message: operation.confirmation,
+                        confirmLabel: operation.label,
+                        cancelLabel: 'Leave it',
+                        // The presence of a confirmation is the host calling this
+                        // destructive, so the button is styled as one.
+                        tone: 'danger',
+                    });
+                    if (!yes)
+                        return;
+                }
+                try {
+                    const done = await operate(connection, at, wanted, {
+                        ...(onFile ? { target: { kind: 'resource', resource: row } } : {}),
+                        /*
+                         * Asked here as well, and separately.
+                         *
+                         * "Discard this file" and "let this host write to your repository"
+                         * are two different questions, and answering the first is not
+                         * answering the second. A client that took the grant silently
+                         * would be one where saying yes to a diff quietly hands over the
+                         * working tree.
+                         */
+                        ask: (request) => confirm(app.layers, {
+                            title: 'Let the host write?',
+                            message: `${operation.label} needs write access to ${request.uri.replace(/^file:\/\//, '')}.`,
+                            confirmLabel: 'Allow',
+                            cancelLabel: 'No',
+                            tone: 'danger',
+                        }),
+                    });
+                    // The host's own sentence about what it did, shown where a refusal
+                    // would be. A silent success on a destructive verb reads as one that
+                    // did not happen.
+                    if (done.message !== undefined)
+                        app.store.set(HOST_ERROR, done.message);
+                }
+                catch (error) {
+                    controller.report(error);
+                }
+            },
+        },
+        {
+            id: 'changes.close',
+            title: 'Back to the file list',
+            category: 'Screens',
+            description: 'Close the open file',
+            // Not in the palette: it is what escape does on one screen, and a
+            // palette entry for it would be offering "go back" as a command.
+            slots: [],
+            when: `${OPEN_FILE}`,
+            run: () => app.store.set(OPEN_FILE, null),
+        },
+        {
+            id: 'go.settings',
+            title: 'Session settings',
+            category: 'Screens',
+            description: 'Settings for this session',
+            slots: ['palette', 'config'],
+            when: `${OPEN}`,
+            run: () => app.screens.push('settings'),
+        },
+        {
+            id: 'go.hosts',
+            title: 'Hosts',
+            category: 'Screens',
+            description: 'Manage all hosts',
+            slots: ['palette'],
+            run: () => app.screens.push('hosts')
+        },
+        /**
+         * Markdown, or the characters the agent typed.
+         *
+         * An agent writes markdown, so drawing it is the default - reading
+         * `**this**` is reading the punctuation instead of the sentence. Off is
+         * for when the punctuation *is* what you are after: copying a fenced
+         * block out with its fence, checking whether a table is a table or four
+         * lines with pipes in them, reading a link's target rather than its
+         * label.
+         *
+         * A toggle rather than two commands, because there are two states and the
+         * screen shows you which one you are in.
+         */
+        {
+            id: 'view.markdown',
+            title: 'Markdown or raw text',
+            category: 'View',
+            description: 'Draw what the agent said as markdown, or as it typed it',
+            slots: ['palette', 'config'],
+            run: () => {
+                const on = app.store.get(MARKDOWN) ?? true;
+                app.store.set(MARKDOWN, !on);
+            },
+        },
+        // Appearance is a registration, not a rewrite. The same graph is mounted
+        // under whichever theme and shell are chosen, which is the claim the
+        // runtime makes and the one an example is meant to be evidence for.
+        /**
+         * The message, in whatever editor the shell says.
+         *
+         * `$VISUAL` before `$EDITOR`, which is the order every program that opens
+         * one uses: `EDITOR` is historically the line editor and `VISUAL` the
+         * full-screen one, and a terminal application wants the second.
+         *
+         * The file is `.md` because that is what a message is - an editor that
+         * highlights by extension gets it right, and one that does not is
+         * unaffected.
+         */
+        {
+            id: 'editor.open',
+            title: 'Edit in $EDITOR',
+            category: 'Compose',
+            description: 'Open the message in an external editor',
+            slots: ['palette'],
+            // The draft it edits belongs to the composer, and only two screens have one.
+            when: `${SCREEN} == 'chat' || ${SCREEN} == 'new'`,
+            run: async () => {
+                const editor = process.env.VISUAL ?? process.env.EDITOR;
+                if (!editor) {
+                    controller.report(new Error('No $VISUAL or $EDITOR is set, so there is no editor to open.'));
+                    return;
+                }
+                // A directory of its own, so the name is not guessable and nothing
+                // else in the temp directory is touched when it is removed.
+                const where = await mkdtemp(join(tmpdir(), 'ahpc-'));
+                const file = join(where, 'message.md');
+                try {
+                    await writeFile(file, app.store.get(DRAFT) ?? '');
+                    await app.suspend(async () => {
+                        await new Promise((resolve) => {
+                            /*
+                             * One string, through the shell.
+                             *
+                             * `$EDITOR` is a command line rather than a path - `code -w` and
+                             * `nvim -c startinsert` are both ordinary values - so it cannot
+                             * be spawned as a program with arguments. And the file has to be
+                             * part of that string: Node's `shell` option joins the argument
+                             * array onto the command rather than passing it to the shell, so
+                             * a `"$1"` placeholder is never substituted and the editor opens
+                             * with no file at all.
+                             */
+                            const quoted = `"${file.replace(/(["\\$`])/g, '\\$1')}"`;
+                            const child = spawn(`${editor} ${quoted}`, { stdio: 'inherit', shell: true });
+                            child.on('close', () => { resolve(); });
+                            child.on('error', () => { resolve(); });
+                        });
+                    });
+                    const text = await readFile(file, 'utf8');
+                    // One trailing newline is the editor's, not the message's - every
+                    // editor that respects POSIX adds it and nobody typed it.
+                    const next = text.replace(/\n$/, '');
+                    app.store.set(DRAFT, next);
+                    controller.draft(next);
+                }
+                catch (error) {
+                    controller.report(error);
+                }
+                finally {
+                    await rm(where, { recursive: true, force: true });
+                }
+            },
+        },
+        {
+            id: 'view.theme',
+            title: 'Theme',
+            category: 'View',
+            description: 'Change the colors and shapes',
+            slots: ['palette', 'config'],
+            // The command says what it needs and the palette asks. Wearing it while
+            // the highlight moves is what makes a theme choosable at all: the names
+            // mean nothing until the screen is in one.
+            args: [{
+                    name: 'id',
+                    type: 'string',
+                    required: true,
+                    choices: app.themes.list().map((theme) => theme.id),
+                    default: app.theme.id,
+                    preview: (value) => {
+                        previous.theme ??= app.theme.id;
+                        if (value === null) {
+                            if (previous.theme)
+                                app.setTheme(previous.theme);
+                            previous.theme = null;
+                            return;
+                        }
+                        app.setTheme(value);
+                    },
+                }],
+            run: (args) => {
+                previous.theme = null;
+                if (args.id)
+                    app.setTheme(String(args.id));
+            },
+        },
+        {
+            id: 'view.shell',
+            title: 'Layout',
+            category: 'View',
+            description: 'Change the layout and controls',
+            slots: ['palette', 'config'],
+            args: [{
+                    name: 'id',
+                    type: 'string',
+                    required: true,
+                    choices: app.shells.list().map((shell) => shell.id),
+                    default: app.activeShell(),
+                    preview: (value) => {
+                        previous.shell ??= app.activeShell();
+                        if (value === null) {
+                            if (previous.shell)
+                                app.setShell(previous.shell);
+                            previous.shell = null;
+                            return;
+                        }
+                        app.setShell(value);
+                    },
+                }],
+            run: (args) => {
+                previous.shell = null;
+                if (args.id)
+                    app.setShell(String(args.id));
+            },
+        },
+        // The composer's control row. Four questions about what the next message
+        // will be sent as, each asked by the palette, anchored above its chip.
+        {
+            id: 'compose.harness',
+            title: 'Harness',
+            category: 'Compose',
+            description: 'Select the agent harness',
+            slots: ['palette'],
+            // Fixed once a session exists: it is the process the conversation is
+            // running in, and a chip offering to change it would be offering a lie.
+            when: `!${OPEN}`,
+            args: [{
+                    name: 'id',
+                    type: 'string',
+                    required: true,
+                    description: 'Which agent runs this',
+                    choices: listAgents,
+                }],
+            run: (args) => {
+                const chosen = known.agents.find((found) => found.provider === String(args.id));
+                if (!chosen)
+                    return;
+                app.store.set(PROVIDER, chosen.provider);
+                // A model belongs to a harness. Kept across a change it names one the
+                // new harness has never heard of, and the host refuses the turn.
+                app.store.set(MODEL, '');
+            },
+        },
+        {
+            id: 'compose.model',
+            title: 'Model',
+            category: 'Compose',
+            description: 'Select the model',
+            slots: ['palette'],
+            // The model rides on the message being composed, so it needs a composer.
+            when: `${SCREEN} == 'chat' || ${SCREEN} == 'new'`,
+            args: [{
+                    name: 'id',
+                    type: 'string',
+                    required: true,
+                    description: 'What the next message runs on',
+                    choices: listModels,
+                }],
+            run: (args) => {
+                // The id, not the label. AHP hangs the model on the message, so this
+                // is what rides on the next `chat/turnStarted`.
+                const chosen = agent()?.models.find((model) => model.id === String(args.id));
+                if (!chosen)
+                    return;
+                app.store.set(MODEL, chosen.id);
+                // A model's answers belong to that model. Carrying them across would
+                // send a level the new model may not accept, in a field the host
+                // reads without asking whether it fits.
+                app.store.set(MODEL_CONFIG, {});
+                controller.offerModel(chosen.options ?? []);
+            },
+        },
+        /*
+         * A session holds chats, and these are how a person moves between them.
+         *
+         * Gated on the agent advertising `multipleChats`: a host that does not is
+         * one where `createChat` MUST NOT be called, so the command is not
+         * offered rather than offered and refused.
+         */
+        {
+            id: 'chat.new',
+            title: 'New chat here',
+            category: 'Session',
+            description: 'Open another conversation in this session',
+            slots: ['palette'],
+            when: CAN_ADD_CHAT,
+            run: () => void controller.createChat(),
+        },
+        /*
+         * The two ways a chat comes from another one.
+         *
+         * Offered only where the agent advertises each: `capabilities.multipleChats`
+         * carries `fork` and `sideChat` separately and a host may have one and not
+         * the other, so this is two commands rather than one with a mode.
+         */
+        {
+            id: 'chat.fork',
+            title: 'Fork from this turn',
+            category: 'Session',
+            description: 'A new chat carrying this conversation up to the turn under the cursor',
+            slots: ['palette'],
+            when: CAN_FORK,
+            run: () => {
+                const from = app.store.get(CHAT_URI);
+                const turn = [...turns(app.store)].reverse().find((one) => one.state !== 'running');
+                if (!from || !turn)
+                    return;
+                void controller.createChat(undefined, { kind: 'fork', chat: from, turnId: turn.id });
+            },
+        },
+        {
+            id: 'chat.side',
+            title: 'Side chat from this turn',
+            category: 'Session',
+            description: 'A new chat with this turn as context, without copying it in',
+            slots: ['palette'],
+            when: CAN_SIDE_CHAT,
+            run: () => {
+                const from = app.store.get(CHAT_URI);
+                const turn = [...turns(app.store)].reverse().find((one) => one.state !== 'running');
+                if (!from || !turn)
+                    return;
+                void controller.createChat(undefined, { kind: 'sideChat', chat: from, turnId: turn.id });
+            },
+        },
+        {
+            id: 'chat.switch',
+            title: 'Chat',
+            category: 'Session',
+            description: 'Read a different conversation in this session',
+            slots: ['palette'],
+            when: HAS_CHATS,
+            args: [{
+                    name: 'chat',
+                    type: 'string',
+                    required: true,
+                    description: 'Which conversation to read',
+                    get default() {
+                        return app.store.get(CHAT_URI) ?? undefined;
+                    },
+                    choices: () => (app.store.get(CHATS) ?? [])
+                        .map((entry, index) => ({
+                        value: entry.resource,
+                        // The title, and its place in the session: two chats begun from
+                        // the same first message are two rows reading the same thing.
+                        label: `${String(index + 1)}. ${entry.title}`,
+                    })),
+                }],
+            run: (args) => { controller.openChat(String(args.chat)); },
+        },
+        {
+            id: 'chat.close',
+            title: 'Close this chat',
+            category: 'Session',
+            description: 'Dispose the conversation being read',
+            slots: ['palette'],
+            when: HAS_CHATS,
+            run: () => {
+                const chat = app.store.get(CHAT_URI);
+                if (chat)
+                    void controller.disposeChat(chat);
+            },
+        },
+        /*
+         * A shell on the host machine.
+         *
+         * Not gated: a host that runs none answers an empty list and refuses to
+         * open one, and the screen says so - which is a better answer than a
+         * command that is missing for a reason nobody can see.
+         */
+        {
+            id: 'terminal.new',
+            title: 'Open a terminal',
+            category: 'Terminal',
+            description: 'Start a shell on the host, in a directory it serves',
+            slots: ['palette'],
+            run: () => {
+                const where = app.store.get(WORKSPACE);
+                void controller.terminals.open(where ? { cwd: where } : {}).then(() => {
+                    app.screens.push('terminal');
+                    app.focus.focus('terminal.input');
+                });
+            },
+        },
+        {
+            id: 'terminal.interrupt',
+            title: 'Interrupt',
+            category: 'Terminal',
+            description: 'Send ctrl+c to the shell',
+            slots: ['palette'],
+            when: OPEN_TERMINAL,
+            // `\u0003` is what a terminal sends for ctrl+c, and the shell is what
+            // decides what to do with it - which is the point: stopping a command
+            // is the shell's job, not this client's.
+            run: () => { controller.terminals.write('\u0003'); },
+        },
+        {
+            id: 'terminal.clear',
+            title: 'Clear terminal',
+            category: 'Terminal',
+            description: 'Empty the scrollback of the open terminal',
+            slots: ['palette'],
+            when: OPEN_TERMINAL,
+            // The host's own action, not a screen wiping what it drew: every client
+            // watching this terminal sees it emptied, which is what `terminal/cleared`
+            // resetting `content` means.
+            run: () => { controller.terminals.clear(); },
+        },
+        {
+            id: 'terminal.rename',
+            title: 'Rename terminal',
+            category: 'Terminal',
+            description: 'Give the open terminal a name',
+            slots: ['palette'],
+            when: OPEN_TERMINAL,
+            args: [{
+                    name: 'title',
+                    type: 'string',
+                    required: true,
+                    description: 'What to call it',
+                }],
+            run: (args) => {
+                const title = String(args.title ?? '').trim();
+                if (title)
+                    controller.terminals.rename(title);
+            },
+        },
+        {
+            id: 'terminal.close',
+            title: 'Close this terminal',
+            category: 'Terminal',
+            description: 'Kill the shell being read',
+            slots: ['palette'],
+            when: OPEN_TERMINAL,
+            run: () => void controller.terminals.close(),
+        },
+        {
+            id: 'go.terminal',
+            title: 'Terminals',
+            category: 'Go',
+            description: 'The shells running on the host',
+            slots: ['palette'],
+            run: () => { app.screens.push('terminal'); },
+        },
+        {
+            id: 'compose.workspace',
+            title: 'Workspace',
+            category: 'Compose',
+            description: 'Select the workspace',
+            slots: ['palette'],
+            when: `!${OPEN}`,
+            // No `choices`, so the palette asks for it as text - the same overlay,
+            // with its field as the answer rather than as a filter. Give it a
+            // `choices` function later and the same chip becomes a list of
+            // workspaces without anything else changing.
+            args: [{
+                    name: 'path',
+                    type: 'string',
+                    required: true,
+                    description: 'Where the agent works. A path on the host, not on this machine.',
+                }],
+            run: (args) => {
+                const path = String(args.path ?? '').trim();
+                if (path)
+                    app.store.set(WORKSPACE, path);
+            },
+        },
+        {
+            id: 'compose.start',
+            title: 'Start a session with what has been typed',
+            category: 'Compose',
+            slots: ['palette'],
+            when: `!${OPEN}`,
+            run: () => {
+                const first = (app.store.get(DRAFT) ?? '').trim();
+                if (!first)
+                    return;
+                void controller.create({
+                    provider: provider(),
+                    ...(app.store.get(WORKSPACE) ? { workingDirectory: app.store.get(WORKSPACE) } : {}),
+                    first,
+                })
+                    .then(() => app.screens.push('chat'))
+                    .catch((error) => controller.report(error));
+            },
+        },
+        {
+            id: 'session.open',
+            title: 'Open session',
+            category: 'Session',
+            description: 'Show the conversation',
+            slots: ['palette'],
+            // It opens the row under the cursor, so it needs one.
+            when: `${SELECTED} || ${OPEN}`,
+            run: (args) => {
+                const uri = (typeof args.uri === 'string' ? args.uri : null) ?? selected();
+                if (!uri)
+                    return;
+                controller.open(uri);
+                app.screens.push('chat');
+            },
+            args: [{ name: 'uri', type: 'string' }],
+        },
+        {
+            id: 'session.new',
+            title: 'New session',
+            category: 'Session',
+            description: 'Start a new conversation',
+            slots: ['palette'],
+            run: () => {
+                // Nothing open, so the control row describes a session that does not
+                // exist yet rather than the one that was on screen a moment ago.
+                controller.close();
+                app.screens.reset('new');
+                app.focus.focus('chat.composer');
+            },
+        },
+        {
+            id: 'session.refresh',
+            title: 'Refresh the catalogue',
+            category: 'Session',
+            description: 'Reload list from the host',
+            slots: ['palette'],
+            keepOpen: true,
+            run: () => void controller.refresh(),
+        },
+        {
+            id: 'session.archive',
+            title: 'Archive / unarchive',
+            category: 'Session',
+            description: 'Hide or show this session',
+            slots: ['palette'],
+            // It acts on the session being read, or the one selected in the catalogue.
+            when: `${OPEN} || ${SELECTED}`,
+            run: () => {
+                const uri = target();
+                // Every session, not the visible ones. An archived session is hidden
+                // by default, so reading the flag off the filtered list found nothing,
+                // fell back to a status of zero, and archived it a second time - which
+                // is a toggle that only ever goes one way.
+                const session = sessions(app.store).find((found) => found.resource === uri);
+                if (!uri || !session)
+                    return;
+                controller.setArchived(uri, (session.status & SessionFlag.IsArchived) === 0);
+            },
+        },
+        {
+            id: 'session.read',
+            title: 'Mark read / unread',
+            category: 'Session',
+            description: 'Mark this session read or unread',
+            slots: ['palette'],
+            // It acts on the session being read, or the one selected in the catalogue.
+            when: `${OPEN} || ${SELECTED}`,
+            run: () => {
+                const uri = target();
+                const session = sessions(app.store).find((found) => found.resource === uri);
+                if (!uri || !session)
+                    return;
+                controller.setRead(uri, (session.status & SessionFlag.IsRead) === 0);
+            },
+        },
+        {
+            id: 'session.dispose',
+            title: 'Dispose session',
+            category: 'Session',
+            description: 'Delete this session',
+            slots: ['palette'],
+            // It acts on the session being read, or the one selected in the catalogue.
+            when: `${OPEN} || ${SELECTED}`,
+            run: async () => {
+                const uri = target();
+                if (!uri)
+                    return;
+                // The host frees the session and tells every other client. Ending
+                // somebody else's conversation is not an undo, so it is asked for.
+                const yes = await confirm(app.layers, {
+                    title: 'Dispose session',
+                    message: 'The host ends this session for every client watching it. The record of what happened stays.',
+                    confirmLabel: 'Dispose',
+                    cancelLabel: 'Keep',
+                    tone: 'danger',
+                });
+                if (yes)
+                    await controller.disposeSession(uri);
+            },
+        },
+        {
+            id: 'session.toggleArchived',
+            title: 'Archived sessions',
+            category: 'Session',
+            description: 'List the sessions that have been put away',
+            slots: ['palette'],
+            keepOpen: true,
+            // A switch, and the palette says which way it is set. The title used to
+            // read `Show archived sessions`, which is one direction of a thing that
+            // has two and says nothing about where it stands.
+            checked: ARCHIVED,
+            run: () => app.store.set(ARCHIVED, !(app.store.get(ARCHIVED) ?? false)),
+        },
+        {
+            id: 'chat.stop',
+            title: 'Stop the turn',
+            category: 'Chat',
+            description: 'Force session to stop running',
+            slots: ['palette'],
+            // On the screen that is showing the turn. A session left open behind
+            // you keeps its status - a blocked one reads 24 for ever - so a clause
+            // that only asked "is something running" swallowed `ctrl+c` on every
+            // other screen from the moment a session was first opened, and the
+            // application could never be closed again.
+            when: `${SCREEN} == 'chat' && ${RUNNING}`,
+            run: () => controller.stop(),
+        },
+        {
+            id: 'chat.approve',
+            title: 'Approve what the agent is waiting on',
+            category: 'Chat',
+            description: 'Approve the tool call ',
+            slots: ['palette'],
+            // There is nothing to approve until the agent has asked.
+            when: `${INPUT}`,
+            run: (args) => controller.approve(typeof args.option === 'string' ? args.option : undefined),
+            args: [{ name: 'option', type: 'string' }],
+        },
+        {
+            id: 'chat.deny',
+            title: 'Deny it',
+            category: 'Chat',
+            description: 'Deny the tool call',
+            slots: ['palette'],
+            // There is nothing to deny until the agent has asked.
+            when: `${INPUT}`,
+            run: () => controller.deny()
+        },
+        {
+            id: 'chat.send',
+            title: 'Send a message',
+            category: 'Chat',
+            description: 'Send a message',
+            slots: ['palette'],
+            // `send` returns without a session, so offering it without one is offering nothing.
+            when: `${OPEN}`,
+            args: [{ name: 'text', type: 'string', required: true, description: 'What to say' }],
+            run: (args) => controller.send(String(args.text ?? '')),
+        },
+        {
+            id: 'chat.focusComposer',
+            title: 'Write a message',
+            category: 'Chat',
+            description: 'Focus the composer',
+            slots: ['palette'],
+            // Focus goes to a field that is only mounted on these two screens.
+            when: `${SCREEN} == 'chat' || ${SCREEN} == 'new'`,
+            run: () => app.focus.focus('chat.composer'),
+        },
+        {
+            /*
+             * Find, in the conversation that is open.
+             *
+             * The same key as the catalogue's filter, on the screen where the
+             * catalogue is not: `ctrl+f` means "look for something in what is in
+             * front of me", and which of the two that is depends on where you are.
+             */
+            id: 'chat.find',
+            title: 'Find in the conversation',
+            category: 'Chat',
+            description: 'Search what has been said in this session',
+            slots: ['palette'],
+            when: `${SCREEN} == 'chat'`,
+            run: () => {
+                app.store.set(FINDING, true);
+                app.focus.focus('chat.find');
+            },
+        },
+        {
+            /*
+             * The next match, and the one before it.
+             *
+             * The matches are block indices and the transcript cursor is a block
+             * index, so going to one is moving the cursor - the feed scrolls to it
+             * and draws it selected, which is what it already does when the arrow
+             * keys walk the conversation. Nothing here has a second idea of where
+             * the search is.
+             *
+             * Wrapping at both ends, because a reader pressing enter at the last
+             * match means "keep going": a find that falls silent at the end of the
+             * conversation reads as broken rather than as finished.
+             */
+            id: 'chat.find.next',
+            title: 'Next match',
+            category: 'Chat',
+            when: `${SCREEN} == 'chat' && ${FINDING}`,
+            run: () => step(1),
+        },
+        {
+            id: 'chat.find.previous',
+            title: 'Previous match',
+            category: 'Chat',
+            when: `${SCREEN} == 'chat' && ${FINDING}`,
+            run: () => step(-1),
+        },
+        {
+            id: 'chat.find.close',
+            title: 'Close the find box',
+            category: 'Chat',
+            // Not in the palette: escape closes it and it is only reachable while
+            // it is open, so a row for it is a row that never applies.
+            when: `${SCREEN} == 'chat' && ${FINDING}`,
+            run: () => {
+                app.store.set(FINDING, false);
+                app.store.set(FIND, '');
+                app.focus.focus('chat.transcript');
+            },
+        },
+        {
+            id: 'session.filter',
+            title: 'Filter the catalogue',
+            category: 'Session',
+            description: 'Filter the catalogue',
+            slots: ['palette'],
+            // The filter box belongs to the catalogue.
+            when: `${SCREEN} == 'sessions'`,
+            run: () => app.focus.focus('chat.filter'),
+        },
+        /**
+         * The detail pane, as a drawer.
+         *
+         * Right opens it and left puts it away: the key points at the pane. It is
+         * on the right of the screen, so right is where you go to read it and
+         * left is the way back to the list - which is also what makes the pair
+         * work above `splitAt`, where the pane is always out and the same two
+         * keys just move the keyboard between the halves.
+         *
+         * Opening is going there. There is no state where the pane is out and
+         * nobody is reading it, because the width follows the focus and a wide
+         * pane nobody asked for is the session list being narrow for nothing.
+         *
+         * Tab still walks the screen. It is the way *out* of a text field, where
+         * left and right are letters, and taking it away would strand anyone who
+         * had reached the filter box.
+         */
+        {
+            id: 'session.openDetails',
+            title: 'Open the session detail',
+            category: 'Session',
+            description: 'Show the detail pane, and read it',
+            slots: ['palette'],
+            // The pane is the catalogue's, so the command is too. Without this it
+            // was offered on every screen and did nothing on all but one.
+            when: `${SCREEN} == 'sessions'`,
+            run: () => {
+                app.store.set(SIDEBAR, true);
+                app.focus.focus('chat.details');
+            },
+        },
+        {
+            id: 'session.closeDetails',
+            title: 'Put the session detail away',
+            category: 'Session',
+            description: 'Hide the detail pane, and give the list the width',
+            slots: ['palette'],
+            when: `${SCREEN} == 'sessions'`,
+            run: () => {
+                // The focus first. Unmounting the pane the keyboard is in leaves the
+                // focus on a node that is no longer there, and the next key goes
+                // nowhere at all.
+                app.focus.focus('chat.sessions');
+                // Only below the split, where the pane is a drawer. Above it, both
+                // panes are always drawn and this key is the way back to the list.
+                const width = app.store.get(SPLIT_AT) ?? SPLIT_DEFAULT;
+                if (app.size.width <= width)
+                    app.store.set(SIDEBAR, false);
+            },
+        },
+        {
+            id: 'chat.focusTranscript',
+            title: 'Read the transcript',
+            category: 'Chat',
+            description: 'Focus the transcript',
+            slots: ['palette'],
+            // The transcript is the conversation's, and nothing else mounts it.
+            when: `${SCREEN} == 'chat'`,
+            run: () => app.focus.focus('chat.transcript'),
+        },
+        {
+            id: 'chat.clearQueue',
+            title: 'Drop queued messages',
+            category: 'Chat',
+            description: 'Drop queued messages',
+            slots: ['palette'],
+            when: `${QUEUE}`,
+            // One dispatch each, because that is what the protocol offers - and the
+            // list comes back from the host rather than being emptied here, so a
+            // message another client queued in the meantime is not silently dropped
+            // by a client that never knew about it.
+            run: () => {
+                for (const message of queue(app.store))
+                    controller.unqueue(message.id);
+            },
+        },
+        {
+            id: 'chat.expand',
+            title: 'Expand / collapse the selected block',
+            category: 'Chat',
+            description: 'Expand / collapse the selected block',
+            slots: [],
+            run: (args) => {
+                const id = String(args.id ?? '');
+                if (!id)
+                    return;
+                const expanded = app.store.get(EXPANDED) ?? {};
+                app.store.set(EXPANDED, { ...expanded, [id]: !expanded[id] });
+            },
+            args: [{ name: 'id', type: 'string' }],
+        },
+        {
+            id: 'chat.running',
+            title: 'Is a turn running',
+            category: 'Chat',
+            description: 'Is a turn running',
+            slots: [],
+            run: () => running(),
+        },
+    ];
+}
+/**
+ * The defaults, with the config file's own bindings over them.
+ *
+ * Naming a chord replaces every default on it rather than adding to them: a
+ * chord that meant one thing globally and another on one screen would still
+ * mean the second after somebody rebound the first, which is not what
+ * rebinding a key means. `null` takes the chord away and binds nothing.
+ */
+function keys(over) {
+    const defaults = shipped();
+    if (!over || Object.keys(over).length === 0)
+        return defaults;
+    const named = new Set(Object.keys(over));
+    return [
+        ...defaults.filter((binding) => !named.has(binding.keys)),
+        ...Object.entries(over)
+            .filter((entry) => entry[1] !== null)
+            .map(([chord, commandId]) => ({ keys: chord, commandId })),
+    ];
+}
+/** What this client ships with. */
+function shipped() {
+    return [
+        // Global: nothing types these, so they are safe wherever focus is.
+        { keys: 'ctrl+p', commandId: 'app.palette' },
+        // Help, where every terminal application has put it.
+        { keys: 'f1', commandId: 'help.keys' },
+        // `alt+g` rather than `ctrl+g`, which is the external editor's key in
+        // every other agent CLI and is kept free for it here.
+        { keys: 'alt+g', commandId: 'bood.toggle' },
+        // The key every other agent CLI opens an editor with, which is why the
+        // creature moved off it.
+        { keys: 'ctrl+g', commandId: 'editor.open' },
+        // The clause is on the *binding*, not only on the command. A binding that
+        // matches has handled the key - whether or not the command it names then
+        // declines to run - so a `when` that lives only on the command swallows
+        // `ctrl+c` and it never reaches the one below that closes the application.
+        { keys: 'ctrl+c', commandId: 'chat.stop', when: `${SCREEN} == 'chat' && ${RUNNING}` },
+        /*
+         * On the terminal screen, `ctrl+c` belongs to the shell.
+         *
+         * It is how a person stops a command, and it reached the binding below
+         * instead - so interrupting a `ping` closed the whole application. The
+         * clause is on the binding for the same reason as the one above: a
+         * binding that matches has handled the key, and a `when` only on the
+         * command swallows it without passing it on.
+         */
+        { keys: 'ctrl+c', commandId: 'terminal.interrupt', when: `${SCREEN} == 'terminal' && ${OPEN_TERMINAL}` },
+        { keys: 'ctrl+n', commandId: 'session.new' },
+        { keys: 'ctrl+r', commandId: 'session.refresh' },
+        /*
+         * `alt+t`, for the reason `alt+m` is the markdown key: an alt chord
+         * arrives as ESC then the letter, which survives SSH, tmux and a console
+         * that has never heard of the kitty protocol. It also leaves `ctrl+t`
+         * unclaimed, which is what the other agent CLIs spend on a todo list.
+         */
+        { keys: 'alt+t', commandId: 'view.theme' },
+        /*
+         * Three, and `alt+m` is the one to reach for.
+         *
+         * Ctrl+M and Return are the same byte. In raw mode the Return key sends
+         * CR, `0x0d`, and this decoder names that `enter` - deliberately, and
+         * with a comment saying so. A terminal speaking the kitty protocol or
+         * xterm's `modifyOtherKeys` sends the two apart and `ctrl+m` arrives as
+         * itself; everywhere else it cannot, and no binding here can change that.
+         * It is kept for the terminals that can, and it is not the one to
+         * document.
+         *
+         * `alt+m` has no such collision: it arrives as ESC then `m`, which this
+         * decoder reads as alt+the key - so it works over SSH, in tmux and on a
+         * console that has never heard of the kitty protocol. Global, because
+         * nothing types it.
+         *
+         * And `m` on its own in the chat scope, where letters are letters only
+         * while the composer holds them - the same bargain `c`, `s` and `t`
+         * already made on this screen.
+         */
+        { keys: 'alt+m', commandId: 'view.markdown' },
+        { keys: 'ctrl+m', commandId: 'view.markdown' },
+        { keys: 'm', commandId: 'view.markdown', scopeId: CHAT_SCOPE },
+        { keys: 'escape', commandId: 'go.back' },
+        // The catalogue.
+        { keys: 'n', commandId: 'session.new', scopeId: SESSIONS_SCOPE },
+        { keys: 'r', commandId: 'session.refresh', scopeId: SESSIONS_SCOPE },
+        { keys: 'a', commandId: 'session.archive', scopeId: SESSIONS_SCOPE },
+        { keys: 'u', commandId: 'session.read', scopeId: SESSIONS_SCOPE },
+        { keys: 'x', commandId: 'session.toggleArchived', scopeId: SESSIONS_SCOPE },
+        { keys: 'd', commandId: 'session.dispose', scopeId: SESSIONS_SCOPE },
+        // The key somebody reaches for without being told, beside the letter they
+        // had to be. Both, because `delete` is the guess and `d` is what the
+        // footer has room to name. It confirms either way - ending somebody
+        // else's conversation is not an undo.
+        { keys: 'delete', commandId: 'session.dispose', scopeId: SESSIONS_SCOPE },
+        // `ctrl+f` rather than `/`, which is what a person reaches for to search
+        // and what the field itself leaves unclaimed.
+        /*
+         * The catalogue's filter and the conversation's find, on the one key a
+         * person reaches for to search.
+         *
+         * The clauses are on the *bindings* and not only on the commands. A
+         * binding that matches has handled the key whether or not the command it
+         * names then declines to run, so the first of these two swallowed
+         * `ctrl+f` on every screen and the second was never reached.
+         */
+        { keys: 'ctrl+f', commandId: 'session.filter', when: `${SCREEN} == 'sessions'` },
+        { keys: 'ctrl+f', commandId: 'chat.find', when: `${SCREEN} == 'chat'` },
+        /*
+         * Walking the matches, while the find box is up.
+         *
+         * The field does not claim up and down, so they reach the bindings. Not
+         * scoped to the conversation: the keyboard is in the field, and a scope
+         * is about which screen a *letter* belongs to. The clause is what keeps
+         * these three off every other key press - unguarded they are `up`, `down`
+         * and `escape` taken away from the whole application.
+         *
+         * `priority` and not position, because escape here has to beat the escape
+         * that leaves the screen and that one is declared above. Order decides a
+         * tie and this is not a tie to settle by which line came first: the find
+         * box is the thing in front of the reader, so it answers first for as
+         * long as it is open.
+         */
+        { keys: 'down', commandId: 'chat.find.next', when: FINDING, priority: 10 },
+        { keys: 'up', commandId: 'chat.find.previous', when: FINDING, priority: 10 },
+        { keys: 'escape', commandId: 'chat.find.close', when: FINDING, priority: 10 },
+        // Scoped, not global, and after the focused node has had its turn: while
+        // the filter box has the keyboard these two are caret movement, and the
+        // runtime offers the key there first.
+        { keys: 'right', commandId: 'session.openDetails', scopeId: SESSIONS_SCOPE },
+        { keys: 'left', commandId: 'session.closeDetails', scopeId: SESSIONS_SCOPE },
+        // The conversation. `i` is the one that gets you into the composer, and
+        // out of it is escape - the pair that makes every other letter reachable.
+        { keys: 'c', commandId: 'go.changes', scopeId: CHAT_SCOPE },
+        { keys: 'f', commandId: 'go.files', scopeId: CHAT_SCOPE },
+        /*
+         * On the changes screen, and nowhere else.
+         *
+         * `]` rather than `tab`, which was the obvious choice and does not work:
+         * tab is how focus moves and the runtime has already spent it before any
+         * binding sees it. `]` is typed by nothing here and reads as "the next
+         * one", which is what it does.
+         *
+         * `r` is a letter, so it lives in the changes scope for the same reason
+         * `c` lives in the chat one - it must not fire while something is being
+         * typed on another screen.
+         */
+        { keys: ']', commandId: 'changes.scope', scopeId: CHANGES_SCOPE },
+        { keys: 'r', commandId: 'changes.review', scopeId: CHANGES_SCOPE },
+        // `x` for "do something to this". The command takes which one as an
+        // argument, so the key opens the picker rather than committing to a verb -
+        // which is right, because the verbs differ per changeset and per host.
+        { keys: 'x', commandId: 'changes.run', scopeId: CHANGES_SCOPE },
+        // Scoped to the screen, so a letter is a letter everywhere else. `enter`
+        // runs one and is the list's own, which leaves the switch and the
+        // one that does not come back.
+        { keys: 'n', commandId: 'automation.new', scopeId: AUTOMATIONS_SCOPE },
+        { keys: 'e', commandId: 'automation.toggle', scopeId: AUTOMATIONS_SCOPE },
+        { keys: 'd', commandId: 'automation.remove', scopeId: AUTOMATIONS_SCOPE },
+        { keys: 's', commandId: 'go.settings', scopeId: CHAT_SCOPE },
+        { keys: 't', commandId: 'chat.stop', scopeId: CHAT_SCOPE },
+        { keys: 'k', commandId: 'go.skills', scopeId: CHAT_SCOPE },
+        { keys: 'p', commandId: 'go.mcp', scopeId: CHAT_SCOPE },
+        /**
+         * An open file closes before the screen does.
+         *
+         * Two bindings on `escape`, and the priority is what decides between
+         * them rather than the order they happen to be written in - the registry
+         * sorts by priority and leaves ties in insertion order, which is a rule
+         * about this array that nothing in this array says.
+         *
+         * The clause is on the binding as well as on the command, for the reason
+         * given above `ctrl+c`: a binding that matches has handled the key even
+         * when the command declines, so an escape with no file open would be
+         * swallowed here and never reach `go.back`.
+         */
+        { keys: 'escape', commandId: 'changes.close', when: `${OPEN_FILE}`, priority: 10 },
+    ];
+}