@sagmans/dsh-tui 0.5.2 → 0.7.0

package/.agents/skills/dsh-tui-update-models/references/model-wiring.md

@@ -0,0 +1,162 @@
+# Model wiring reference
+
+Companion to [SKILL.md](../SKILL.md): exact fields, files, and checks.
+
+## Resolution order
+
+1. Bundle layers in `cordis.yml`, in order.
+2. The profile patch `~/.dsh/profiles/<profile>/cordis.patch.yml`, entry by entry:
+   `id` targeted config, `disabled`, `insert`.
+3. A patch `config` **replaces** that row's base config; fields it omits fall back
+   to the schema default, not to the bundle's value.
+4. The model directory a profile sees is owned by whichever row is enabled:
+   `llm-pi-ai` (additive provider config), `dsh-provider-extra` (owned catalog),
+   or both, if the profile is not using exclusive ownership.
+
+Exclusive ownership is a set of disable rows plus the catalog itself:
+
+```yaml
+- { "id": "agent-default-model", "disabled": true }
+- { "id": "llm-pi-ai", "disabled": true }
+- { "id": "llm-deepseek", "disabled": true }
+- id: dsh-provider-extra
+  config: { catalog: { version: 1, ... } }
+```
+
+## `llm-pi-ai` provider config
+
+```yaml
+- id: llm-pi-ai
+  config:
+    providers:
+      qwen-token-plan:
+        apiKeyEnv: QWEN_TOKEN_PLAN_API_KEY   # env var holding the key
+        baseURL: https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
+        api: openai-completions              # optional wire override
+        models:
+          - id: qwen3.8-max                  # served as-is
+          - id: deepseek-v4.1-flash
+            name: DeepSeek V4.1 Flash
+            contextWindow: 1000000
+            maxTokens: 384000
+            input: [text, image]
+            reasoningEfforts: { low: low, high: high, max: max }
+            compat:
+              supportsStore: false
+              supportsDeveloperRole: false
+              supportsReasoningEffort: true
+              supportsStrictMode: true
+              thinkingFormat: qwen
+```
+
+An id that the installed catalog already describes needs no restatement. An id it
+does not describe needs the metadata (or a `template` sibling to clone).
+
+## `dsh-provider-extra`
+
+Two config generations exist; a profile normally uses one:
+
+| Config | Use |
+| --- | --- |
+| Additive: `routeId`, `displayName`, `apiKeyEnv`, `fallbackSessionId`, `extraModels`, `models`, `codexExtraModels`, `codexModels`, `codexTransport` | add a gateway or subscription route beside whatever else the profile serves |
+| `catalog` v1 | own the entire directory: ids, aliases, metadata, and the default selection |
+
+Catalog fields:
+
+```yaml
+catalog:
+  version: 1                      # exactly 1
+  default:                        # null only when the catalog is empty
+    { provider: opencode-go-session, model: deepseek-flash, reasoningEffort: max }
+  providers:
+    - id: opencode-go-session     # the id every selection and alias check uses
+      name: OpenCode Go (session)
+      source: opencode-go         # pi-ai provider id: its installed data is the base
+      baseURL: https://api.x.ai/v1            # optional
+      transport: sse                          # optional
+      fallbackSessionId: dsh-provider-extra   # optional
+      auth: { apiKeyRef: OPENCODE_GO_API_KEY }        # or { credentialProvider: openai-codex }
+      models:
+        - id: deepseek-flash
+          name: DeepSeek V4.1 Flash
+          aliases: [deepseek-v4.1-flash]      # extra ids that resolve to this model
+          template: deepseek-v4-flash         # clone wire behavior when the source lacks the id
+          defaultMaxTokens: 384000            # request ceiling; metadata.maxTokens overrides
+          metadata:
+            api: openai-completions
+            reasoning: true
+            input: [text, image]
+            cost: { input: 0.22, output: 0.66, cacheRead: 0.007, cacheWrite: 0 }
+            contextWindow: 1000000
+            maxTokens: 384000
+            thinkingLevelMap: { off: null, minimal: null, low: low, medium: null, high: high, xhigh: null, max: max }
+            compat: { supportsStore: false, supportsDeveloperRole: false, supportsReasoningEffort: true, supportsStrictMode: true, thinkingFormat: qwen }
+```
+
+Behaviour:
+
+| Case | Result |
+| --- | --- |
+| `template` names a sibling the source ships | clone its wire behavior and metadata |
+| `template` names nothing | that model lands in the route's diagnostics; the rest of the route still serves |
+| a `models` whitelist names an id nothing provides | the whole route is refused - a typo there is a broken deployment |
+| two providers share an id | composition error |
+| `default` names a model outside the catalog | composition error |
+| `reasoningEffort` unsupported by the model | composition error |
+
+## Where the base data comes from
+
+```sh
+# the harness install owns the pi-ai catalog the profile resolves against
+DSH=$(readlink -f "$(command -v dsh)")
+PI_AI="${DSH%/lib/bin.js}/node_modules/@earendil-works/pi-ai"
+ls "$PI_AI/dist/providers/data"      # one JSON per provider source, keyed by api
+```
+
+A JSON entry is the whole truth for a `source`: `id`, `name`, `cost`,
+`contextWindow`, `maxTokens`, `input`, `reasoning`, `thinkingLevelMap`, `compat`.
+A model declared without `template` and without `metadata` is served exactly as
+this file describes it, so an id the vendor renamed or repriced shows stale
+numbers until the catalog declares them. An entry that carries its own complete
+`metadata` needs no installed entry at all, which is how a route the harness does
+not describe is wired.
+
+## Credentials
+
+| Field | Meaning |
+| --- | --- |
+| `apiKeyEnv` | read the key from this environment variable |
+| `apiKeyRef` | read it from the profiles' stored credentials under this reference |
+| `credentialProvider` | use a login flow's stored credentials (codex subscriptions) |
+
+Keys never belong in a patch, a settings file, or a repository. Put launch-time
+values in `$DSH_HOME/.env` or the environment. A provider row whose credential is
+missing fails its route only; other routes still serve.
+
+## Verify
+
+```sh
+dsh --profile tui list-models        # provider/model<TAB>display name, one per reachable route
+~/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs --home "$DSH_HOME"
+```
+
+`list-models` exits zero only after printing a line, so a deployment that
+advertises nothing cannot pass for one that was enumerated.
+
+For every model you touched, confirm against the vendor's own page:
+
+1. price per 1M tokens for input, output, cached input, cache write;
+2. context window and maximum output tokens (a "272K" beside "above 272K input
+   is priced 2x" is a billing threshold, not the window);
+3. the accepted reasoning effort values, and how the vendor spells "no reasoning"
+   (OpenAI: `none`; codex: omit the parameter);
+4. whether the route bills per token at all - a credit or token plan wants cost
+   `0`, a metered API wants its published rates;
+5. that an `xhigh` or `max` mapping exists when the vendor documents one.
+
+A model with no vendor page (stealth releases, previews) is documented only by the
+routing catalog: its pi.dev model page and `models.dev/api.json`.
+
+Then run the profile against a cloned home before the real one - see the
+`dsh-tui-dogfood` skill - and `pnpm run build` any linked bundle first: a linked
+profile loads `lib/`, not `src/`.

package/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * Print the model directory a dsh profile resolves, with the provenance of
+ * every field.
+ *
+ * The surface reads prices, context windows, and reasoning levels from the
+ * composition, not from the vendor's page, so an inherited or stale value is
+ * invisible in the UI. This reads the same two inputs the resolver does - the
+ * owned catalog in the profile patch, and the installed pi-ai provider data -
+ * and names where each number came from: "installed" for the source's own
+ * entry, "template:<id>" for a clone, "metadata" for what the catalog declares.
+ * An entry the catalog spells out completely needs no installed entry at all,
+ * so a missing harness install must not hide it.
+ *
+ * Usage: dump-model-catalog.mjs [--home <dsh home>] [--profile <name>] [--json]
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
+/** Fields a catalog entry may inherit, and the layer each value came from. */
+const INHERITED_FIELDS = ['contextWindow', 'maxTokens', 'cost', 'input', 'reasoning', 'thinkingLevelMap', 'api']
+const INSTALLED = 'installed'
+const METADATA = 'metadata'
+const ABSENT = 'none'
+
+/** The levels pi-ai offers: a null mapping removes one, and xhigh/max need one. */
+export function supportedLevels(levelMap) {
+  return LEVELS.filter((level) => {
+    const mapped = levelMap?.[level]
+    if (mapped === null) return false
+    if (level === 'xhigh' || level === 'max') return mapped !== undefined
+    return true
+  })
+}
+
+function parseArgs(argv) {
+  const options = { home: process.env.DSH_HOME ?? join(homedir(), '.dsh'), profile: 'tui', json: false }
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index]
+    if (flag === '--json') options.json = true
+    else if (flag === '--home') options.home = argv[++index]
+    else if (flag === '--profile') options.profile = argv[++index]
+    else throw new Error('unknown argument ' + flag)
+  }
+  return options
+}
+
+/** The pi-ai data directory of the harness install the launcher belongs to. */
+function dataDirectory() {
+  try {
+    const bin = execFileSync('sh', ['-c', 'command -v dsh'], { encoding: 'utf8' }).trim()
+    const root = join(realpathSync(bin), '..', '..')
+    return join(root, 'node_modules', '@earendil-works', 'pi-ai', 'dist', 'providers', 'data')
+  } catch {
+    // No harness install is a supported reading: declared entries still resolve.
+    return undefined
+  }
+}
+
+/** Every JSON patch entry that configures the owned catalog, last one winning. */
+export function catalogConfig(patch) {
+  const lines = readFileSync(patch, 'utf8').split('\n')
+  let catalog
+  for (const line of lines) {
+    if (!line.startsWith('- {') || !line.includes('"catalog"')) continue
+    const entry = JSON.parse(line.slice(2))
+    if (entry.config?.catalog !== undefined) catalog = entry.config.catalog
+  }
+  return catalog
+}
+
+export function providerData(directory, source) {
+  if (directory === undefined) return undefined
+  try {
+    return JSON.parse(readFileSync(join(directory, source + '.json'), 'utf8'))
+  } catch {
+    return undefined
+  }
+}
+
+/** Look one id up across a provider's api maps; an api in the spec disambiguates. */
+function lookup(data, id, api) {
+  if (data === undefined) return undefined
+  for (const [key, models] of Object.entries(data)) {
+    if ((api === undefined || key === api) && models[id] !== undefined) return { ...models[id], api: models[id].api ?? key }
+  }
+  return undefined
+}
+
+/** Resolve one catalog entry against the installed data it may inherit from. */
+export function resolve(spec, data) {
+  const metadata = spec.metadata ?? {}
+  const declared = Object.keys(metadata).length > 0
+  const cloneOf = spec.template ?? spec.id
+  const base = lookup(data, cloneOf, metadata.api)
+  if (base === undefined && !declared) {
+    return { error: 'no source entry for ' + cloneOf + '; declare a template or metadata' }
+  }
+  const merged = { ...base, ...metadata, id: spec.id, name: spec.name ?? base?.name ?? spec.id }
+  merged.maxTokens = metadata.maxTokens ?? spec.defaultMaxTokens ?? base?.maxTokens
+  const origins = {}
+  for (const field of INHERITED_FIELDS) {
+    const declaredValue = field === 'maxTokens' ? metadata.maxTokens ?? spec.defaultMaxTokens : metadata[field]
+    if (declaredValue !== undefined) origins[field] = METADATA
+    else if (base === undefined) origins[field] = ABSENT
+    else origins[field] = spec.template === undefined ? INSTALLED : 'template:' + spec.template
+  }
+  return { model: merged, origins, levels: supportedLevels(merged.thinkingLevelMap) }
+}
+
+function rowsOf(catalog, directory) {
+  const rows = []
+  for (const provider of catalog.providers ?? []) {
+    const data = providerData(directory, provider.source)
+    for (const spec of provider.models ?? []) {
+      const result = resolve(spec, data)
+      const route = provider.id + '/' + spec.id
+      if (result.error !== undefined) {
+        rows.push({ route, error: result.error })
+        continue
+      }
+      const cost = result.model.cost ?? {}
+      rows.push({
+        route,
+        name: result.model.name,
+        api: result.model.api,
+        contextWindow: result.model.contextWindow,
+        maxTokens: result.model.maxTokens,
+        cost: '$' + [cost.input, cost.output, cost.cacheRead, cost.cacheWrite].join('/') + ' per 1M',
+        levels: result.levels.join(','),
+        origins: INHERITED_FIELDS
+          .map(field => [field, result.origins[field]])
+          .filter(([, origin]) => origin !== INSTALLED)
+          .map(([field, origin]) => field + '=' + origin)
+          .join(' ') || 'all installed',
+      })
+    }
+  }
+  return rows
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const patch = join(options.home, 'profiles', options.profile, 'cordis.patch.yml')
+  const catalog = catalogConfig(patch)
+  if (catalog === undefined) {
+    process.stderr.write('no owned catalog in ' + patch + '\n'
+      + 'this profile wires models another way; see references/model-wiring.md\n')
+    process.exit(1)
+  }
+  const directory = dataDirectory()
+  if (directory === undefined) {
+    process.stderr.write('no harness install found; entries that inherit from it cannot be checked\n')
+  }
+  const rows = rowsOf(catalog, directory)
+  const unresolved = rows.filter(row => row.error !== undefined).length
+  if (options.json) {
+    process.stdout.write(JSON.stringify({ default: catalog.default ?? null, rows }, null, 2) + '\n')
+  } else {
+    for (const row of rows) {
+      if (row.error !== undefined) {
+        process.stdout.write(row.route + '\n  UNRESOLVED: ' + row.error + '\n')
+        continue
+      }
+      process.stdout.write(row.route + '\n  ' + row.name + ' | ' + row.api + ' | ctx ' + row.contextWindow
+        + ' | max ' + row.maxTokens + ' | ' + row.cost + ' | efforts ' + row.levels + '\n  inherited: ' + row.origins + '\n')
+    }
+    process.stdout.write('default: ' + JSON.stringify(catalog.default ?? null) + '\n')
+  }
+  process.exit(unresolved === 0 ? 0 : 1)
+}
+
+// Importing the resolver must not run the CLI: the spec reads it that way.
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main()

package/README.md

@@ -6,7 +6,7 @@ Status: **v1 feature-complete; published on npm as `@sagmans/dsh-tui`.** The sur
 
 ## Install
 
-A profile keeps this plugin as one bundle layer. Install it from a checkout of this repository, or from the registry (`0.1.0` or later). Both paths need Node.js >= 22.19 and `pnpm` on `PATH`. Both need a real terminal: stdin and stdout must be TTYs.
+A profile keeps this plugin as one bundle layer. Install it from a checkout of this repository, or from the registry (`0.1.0` or later). Both paths need Node.js >= 22.19 and `pnpm` on `PATH`. Interactive sessions need a real terminal: stdin and stdout must be TTYs.
 
 ### From a plugin checkout
 
@@ -30,6 +30,33 @@ dsh --profile tui
 
 Releases are published, so this path works today. A checkout stays the path for unreleased work.
 
+### Install the dogfood skill (optional)
+
+Run this explicit command after you add the plugin:
+
+```sh
+dsh --profile tui install-skills
+```
+
+The command copies `dsh-tui-dogfood` to
+`~/.agents/skills/dsh-tui-dogfood/`. Agents can then load it from any dsh
+plugin repository. The skill uses a cloned dsh home, so tests do not change
+your real profile. A first install needs no TTY. `npm install` does not copy
+skills into your home.
+
+If the skill exists, the command asks `Update existing skill? [y/N]` in a
+terminal. Only `y` or `yes` replaces it. Enter or `n` keeps the existing
+copy. To update without a prompt, including in non-interactive runs, use:
+
+```sh
+dsh --profile tui install-skills --update
+```
+
+Updating removes any local changes inside the previous skill directory.
+The command stages the new copy before replacement and restores the old
+copy if replacement fails. If cleanup fails after replacement, the new copy
+stays installed and the command reports the old backup path.
+
 ### Confirm the plugin mounted
 
 The profile records its layers in `$DSH_HOME/profiles/tui/package.json` (`~/.dsh` by default). `@sagmans/dsh-tui` must appear in `dsh.profile.bundles`:
@@ -117,8 +144,18 @@ dsh --profile tui --preset minimal          # start in a shipped mode other than
 dsh --profile tui --model deepseek-chat
 dsh --profile tui --no-color
 dsh --profile tui --no-bell            # do not ring when a long turn finishes
+dsh --profile tui list-models          # print every provider/model the picker can reach
 ```
 
+`list-models` prints one line per route the `/model` picker can reach —
+`provider/model`, a tab, then the model's display name — in picker order:
+providers as the llm service registered them, then each provider's own model
+order. It writes plain stdout, so it works piped or redirected, never opens the
+alternate screen, and exits 0 after printing at least one route. When the
+profile has no llm service, when the provider listing cannot be read, or when
+nothing is configured to advertise a model, it names the reason on stderr and
+exits 1.
+
 Every key below is a shipped default. `/keys` opens every action the surface
 and its library can perform as a list you filter as you type, with the keys in
 force, and the `keys:` section moves any of them — see [Keys](#keys).
@@ -140,6 +177,8 @@ force, and the `keys:` section moves any of them — see [Keys](#keys).
 | Ctrl+X then Y | copy the last answer to the clipboard |
 | Ctrl+X then E | edit the draft in `$VISUAL` (or `$EDITOR`) and take back what it saves |
 | Ctrl+X then ? | search the key map: every action and the keys in force, in a box over the transcript |
+| Ctrl+X then U | undo the last prompt: hide its turn, land on the previous answer, and put the prompt back in the bar |
+| Ctrl+X then R | redo the undone prompt |
 | `y` / `n` / Esc / Ctrl+C | allow once, reject, or cancel a pending approval |
 | digits / space / ↑↓ / Enter / Esc / Ctrl+C | answer a question: pick or toggle, confirm, or skip one with Esc; Ctrl+C abandons the whole batch with no answers, like an aborted call; `0` answers with your own text in the input bar |
 | ↑↓ / Ctrl+P / Ctrl+N | move through the open list: a picker's rows, a question's options, or the completion menu above the bar |
@@ -160,12 +199,15 @@ force, and the `keys:` section moves any of them — see [Keys](#keys).
 | `/preset` | pick the agent mode for this session from the roster |
 | `/preset <id>` | switch to that mode, while the session is still blank |
 | `/new [title]` | start a fresh session without leaving the terminal (`ctrl+x` then `n` starts one untitled) |
+| `/reload` | compose this session's agent again and replay its transcript, so an edited preset or skill file reaches the session; a running turn or a queued prompt is refused with `ctrl+c` as the way forward |
 | `/jobs` | list background jobs with their state and duration |
 | `/jobs read <id>` / `/jobs kill <id>` | show the tail of a job's output, or stop it |
 | `/subagents` | list the delegations this session started, with their provider and age |
 | `/subagents open <id\|last>` | read a child's own conversation in place; `ctrl+b` comes back |
 | `/subagents kill <id>` | stop a live child agent |
 | `/fork [title]` | branch this conversation after its last completed turn and continue in the branch |
+| `/undo` | hide the newest prompt's turn and put that prompt back in the bar (`ctrl+x` then `u`) |
+| `/redo` | step forward again after an undo (`ctrl+x` then `r`) |
 | `/rename <title>` | title this session; the picker shows it instead of the session id |
 | `/export [path]` | write the visible transcript as markdown (default `dsh-session-<id>.md`) |
 | `/resume` | open another stored session without leaving the terminal |
@@ -192,18 +234,20 @@ prefix alone — enough to say that a key is waiting, without reciting the map
 and a key that finishes nothing is typed as usual rather than swallowed, so a
 prefix pressed by accident costs nothing; `/help` lists the chords, `m` for the
 model picker, `p` for plan mode, `n` for a fresh session, `y` for the last
-answer, `s` to stash the draft, `l` for the stashes, `e` for the draft in the
-reader's own editor, and `?` for the key map.
+answer, `u` to undo the last prompt, `r` to redo it, `s` to stash the draft,
+`l` for the stashes, `e` for the draft in the reader's own editor, and `?` for
+the key map.
 `keys.chord.prefix: alt+x` starts the chord with another key — or with a list of
 them, as so many ways in — and `prefixWindow: 0` waits for the next key instead
 of lapsing; every second key is a row of its own (`chord.model`, `chord.plan`,
 `chord.new`, `chord.copy`, `chord.stash`, `chord.stashes`, `chord.editor`,
-`chord.keys`), so a chord can be respelled whole. A prefix that is not a modifier
+`chord.keys`, `chord.undo`, `chord.redo`), so a chord can be respelled whole. A prefix that is not a modifier
 chord, that the surface or the prompt bar already answers (`ctrl+c`, `ctrl+s`),
 or that the terminal keeps (`ctrl+q`) is refused with the reason, and the
 shipped keymap stays in force. The chords themselves are the commands they stand
-for: `m`, `p`, `n`, `y`, `s`, `l`, and `?` ask the same dispatcher `/model`,
-`/plan`, `/new`, `/copy`, `/stash`, `/stash-list`, and `/keys` do; `e` is the
+for: `m`, `p`, `n`, `y`, `s`, `l`, `u`, `r`, and `?` ask the same dispatcher
+`/model`, `/plan`, `/new`, `/copy`, `/stash`, `/stash-list`, `/undo`, `/redo`,
+and `/keys` do; `e` is the
 one chord with no command behind it, because it opens a program rather than
 running a line. Plan mode is the one pair that cannot share a name: `/plan` only
 enters, so the chord names `/plan off` instead when the agent is in plan mode —
@@ -214,7 +258,9 @@ An approval or a question draws inline above the editor and takes the keyboard.
 
 While a turn runs, a prompt submitted into the editor waits in the agent's own inbox instead of disappearing: it is drawn above the editor in the input bar's own frame, faint and italic, and moves into the transcript when the agent takes it — where it keeps that frame in the prompt's own mint shade, so what the reader typed is never mistaken for what the agent said. Its markdown lays out inside that frame, so a list or a fence reads in the same box it was typed into. `editor.queued` and `editor.queued.more` restyle or hide the waiting rows; `transcript.user` restyles the submitted prompt. A reply is drawn in a frame of its own, so one exchange reads as two objects rather than as a box followed by a stream of rows: `transcript.assistant.border` restyles that frame, and hiding it draws the reply bare. `ctrl+c` takes them back: an interrupt drops whatever the agent has not started, so the waiting prompts are read first and put into the bar before the turn is stopped.
 
-Every submitted line is also kept in a global prompt history at
+Copying is read back through what the surface drew rather than through the screen, so a selection is the words alone: dragging across a message takes its box with it on screen, and the surface takes its own frame back out before the text reaches the clipboard — the sides, the padding beside them, and the rules above and below. A selection that covers a whole message, two of them, or a part of one is read the same way, and a row the transcript did not draw — the editor's own bar, a picker's card — is copied exactly as it read, and a selection that was nothing but frame is handed back as the reader made it, because a copy is never emptied. The frame still comes back in a copy taken with the terminal's own selection — Shift held while dragging, or a terminal that keeps selection to itself — which is the one path no program can filter.
+
+When prompt history is enabled, each submitted line is kept in a global history at
 `$DSH_HOME/prompt-history.json`. Typing the start of a prompt that was sent
 before draws the rest of the newest match after the cursor in a faint shade.
 `Ctrl+E` takes the whole suggestion and the word-movement key takes the next
@@ -319,8 +365,8 @@ must not also be a way to lose the work.
 
 Every styled element is a named token with a shipped default, and every key is
 an action with one, so the surface can be restyled and rebound without touching
-code. Preferences live in the same user-settings document as every other
-(`$DSH_HOME/settings.yaml`), under a `dsh-tui:` section:
+code. Released hosts with section APIs store preferences in
+`$DSH_HOME/settings.yaml`, under a `dsh-tui:` section:
 
 ```yaml
 dsh-tui:
@@ -355,6 +401,61 @@ dsh-tui:
       hidden: true            # the element renders nothing at all
 ```
 
+Config-backed source hosts store the same preference fields in the TUI entry's
+`config` in the active profile patch. Use the actual entry ID, normally `tui`,
+not the legacy `dsh-tui` namespace. For example:
+
+```yaml
+- id: tui
+  config:
+    theme: violet-orbit
+    history:
+      enabled: false
+      ghost: false
+```
+
+The plugin exports a Config schema for all preferences shown above, including
+`prefix`, `prefixWindow`, and `keys`. Launch fields such as `sessionId`,
+`model`, and `provider` remain separate from live preference edits.
+The settings service owns persistence. TUI does not create another preference store.
+It uses released `installSection` or `register` APIs, or Config-backed
+`describe` and revision-checked `update` APIs. Unsupported or read-only writes
+show a notice instead of reporting success. A rejected theme selection restores
+the applied theme, and `/theme tokens` reports that same appearance.
+
+On Config-backed hosts, absent `history.enabled` and `history.ghost` stay off.
+Set each switch to `true` explicitly to enable it. This prevents recording while
+the host's asynchronous legacy import is pending or has failed. Released section
+hosts retain their existing defaults. If the host reports unreadable preferences,
+history stays off. Readable `false` switches survive errors in other fields.
+Malformed updates retain the last valid appearance and do not overwrite their source.
+
+When public descriptors expose raw user layers, history checks those layers at use
+time. A readable opt-out survives rejected siblings even without a change event.
+Another rejected opt-in cannot clear this protection; a valid committed update can.
+A released-provider limit remains: after an absent user section, rejected scalar
+sections can produce identical public descriptors. TUI cannot detect that transition
+without host validity metadata, so normal released defaults remain active.
+
+The inspected source host has no legacy import alias from `dsh-tui` to `tui`.
+Exporting Config does not resolve that namespace mismatch. The host can rename
+`settings.yaml` to `settings.yaml.imported` before import completes.
+TUI does not retry or restore that file automatically. Preserve current privacy
+opt-outs and copy only the intended legacy fields into the actual TUI entry's
+`config`. Keep the original file for rollback.
+
+Live Config edits require the loaded schema runtime to create native volatile
+references. The released schemastery 3.18.2 implementation used by this checkout's
+unit tests lacks that API. A source host can resolve a different implementation
+with the same version label. TUI checks the loaded implementation and actual
+references, not the package version or CLI identity.
+
+If the loaded schema runtime lacks native support, TUI exports ordinary fields
+rather than unsupported live metadata. TUI then rejects Config-backed writes,
+and the host cannot import preferences through its volatile-field settings API.
+Reading row preferences still works, and ordinary profile changes use the host's
+reload lifecycle. Native schema-backed hosts can apply live preference updates.
+
 Every field is optional, so a section that changes one shade is enough. The
 document is hot-reloaded: an edit restyles a running session and re-arms the
 keymap on the next press, and `/theme` shows each element's effective value and
@@ -609,11 +710,11 @@ A question whose id ends in `:secret` declares its typed answer a credential: th
 
 The fold is durable-only: the live stream decorates the row that is still being written, and everything else — cards, reasoning, work state, compaction markers — comes from the log, so a resumed session renders what the live one did. Subagent start and finish are the exception: they arrive as service events, and the transcript shows them as decoration because the durable record of a delegation is the tool call that asked for it.
 
-Tool cards are folded by default: a card draws one header row — the tool, its argument clipped to the configured budget, and the facts the result measured — so a long read, diff, or search cannot bury the conversation. A shell card's row also carries the exit status and the count of output rows waiting behind the fold, because its output is the answer the reader asked for and a fold that left no trace of it would read as a call that produced nothing. Clicking a card opens or folds that one message; `Ctrl+O` opens or folds every card at once, and `tools:` in the [settings](#settings) decides how each tool starts and whether a fold hides its rows or keeps a `tail` of them.
+Tool cards are folded by default: a card draws one header row — the tool, its argument clipped to the configured budget, and the facts the result measured — so a long read, diff, or search cannot bury the conversation. A call that has not answered yet names itself in the running colour, `tool.running.title`, and ends that row with the whole seconds it has been waiting, in `tool.running.elapsed`, once it has waited one, so a reader can tell the call they are watching from the one below it that already finished; both give way to the measured facts the moment the result lands. A call that failed names itself in the failed colour, `tool.failed.title` — including a shell whose command exited non-zero or died on a signal, which is a failure whether or not the tool that ran it said so. A shell card's row also carries the exit status and the count of output rows waiting behind the fold, because its output is the answer the reader asked for and a fold that left no trace of it would read as a call that produced nothing. Clicking a card opens or folds that one message; `Ctrl+O` opens or folds every card at once, and `tools:` in the [settings](#settings) decides how each tool starts and whether a fold hides its rows or keeps a `tail` of them.
 
-A PTC card is the one card with children: every call the `run_code` program dispatched hangs off the card that made it, and each draws under the header as the tool's own name and argument, on one row cut at the screen edge whether the card itself is open or folded — a program's work must stay legible without opening its card. Clicking one of those rows opens that call's argument in full and leaves its neighbours and the card as they were; a shell call also brings back the rows it printed, because the program's return value is all the card itself keeps. `Ctrl+Y` hides or shows them all, and `subcalls: collapsed` starts every session with them hidden; see [Settings](#settings).
+A PTC card is the one card with children: every call the `run_code` program dispatched hangs off the card that made it, and each draws under the header as the tool's own name and argument, on one row cut at the screen edge whether the card itself is open or folded — a program's work must stay legible without opening its card. Each of those rows names its own call in the colour of what that call is doing — `tool.subcall.running` while the program is waiting on it, `tool.failed.title` when it failed, and `tool.subcall.title` once it is back — and a settled row keeps the one line the tool itself drew about its outcome, in `tool.terminal.status` where that tool declares one. A shell call therefore reads `bash pnpm test · exit 0` when it worked and the same row in red, with `exit 1`, when it did not, so a program's work reads row by row without opening the card. The program's own row is the one card that shows no mark: its timer is what says it is still running, and it is also what the card keeps when the program answers — the total it ran for, drawn in `tool.elapsed.done`, dimmed and italic, because the work it measured is over. Clicking one of those rows opens that call's argument in full and leaves its neighbours and the card as they were; a shell call also brings back the rows it printed, because the program's return value is all the card itself keeps. `Ctrl+Y` hides or shows them all, and `subcalls: collapsed` starts every session with them hidden; see [Settings](#settings).
 
-A card's header names the tool, then the argument the call was made with — a path or a command — in the `tool.args` colour, then the facts the result measured: a read reports its line range, line count, and token size; a file change that carried no prior content to compare against reports its lines and tokens; one that did reports added, changed, and removed lines as `+n ~n -n` in green, yellow, and red. Each stat is its own token, so any of them can be recoloured or hidden independently.
+A card's header names the tool, then the argument the call was made with — a path or a command — in the `tool.args` colour, then the facts the result measured: a read reports its line range, line count, and token size; a file change that carried no prior content to compare against reports its lines and tokens; one that did reports added, changed, and removed lines as `+n ~n -n` in green, yellow, and red. Each stat is its own token, so any of them can be recoloured or hidden independently, and so are the elements a call in flight is drawn with — hiding `tool.running.elapsed` leaves the name in its running colour, hiding `tool.running.title` leaves the seconds counting, hiding `tool.elapsed.done` takes the total off a program's settled row, and a dispatched row is toned the same way per state with `tool.subcall.running` and `tool.subcall.title`. A state is only how a name is painted, so hiding one of those colours leaves the name in the colour a call with no state is read in rather than taking the name away.
 
 The bundle also takes the base's global agent rows out of the composition, twenty-three of them. Every one is a row the shipped modes supply per session instead, so leaving it mounted registers the same tool names in two layers and doubles each prompt section it owns. What stays mounted is the host: sessions, storage, models, permissions, jobs, and the command registry.
 
@@ -649,14 +750,14 @@ The list the dock and `/todo` draw follows the same lifetime every other surface
 | This surface | Herdr |
 |---|---|
 | the screen is taken, before any session opens | `idle`, claiming the pane's agent row |
-| `turn/start` | `working` |
+| the agent's driver starts, including a run of turns chained through pending work | `working` |
 | an approval, a question, or a picker takes the keyboard | `blocked`, with that card's title sent along |
-| the decision settles | `working` if a turn is open, otherwise `idle` |
-| `turn/end` | `idle` |
+| the decision settles | `working` if the driver is running, otherwise `idle` |
+| the agent's driver stops with nothing pending | `idle` |
 | a session opens, resumes, forks, or is switched to | its id and reason, plus the `dsh_session` / `dsh_cwd` pane tokens |
 | exit, signal, or boot failure | `herdr pane release-agent`, so no row is left waiting on a process that is gone |
 
-A wait outranks a running turn: a turn waiting on a human is not making progress, and the wait is the only thing worth acting on from a wall of panes. Reports are sequenced per source, so a delivery that arrives late cannot undo the state the surface already moved past, and a state Herdr is already showing is not sent again. A report is only counted as made when Herdr acknowledges it: one that failed is tried again — soon after, then with a growing wait — and a session identity Herdr never confirmed travels with the next report of any kind. The retry cannot wait for another state change, because the pane may have nothing left to say: a turn that ended while the socket was down produces no further event. States still waiting to be sent are collapsed into the newest one, so a socket that was down for a minute is told where the pane is rather than where it has been. The release carries the next number in that same sequence for the same reason: Herdr reads one that cannot beat the pane's last report as stale, and a stale release leaves the row waiting on a process that is gone. It also stops reporting first — a claim landing after the release would take the row back for a process that is leaving — and the report already on the wire is waited for before the row goes back, because Herdr ignores the release of a pane nothing has claimed yet and that late report would then claim it. What is still waiting behind it is dropped rather than sent.
+A wait outranks a running driver: an agent waiting on a human is not making progress, and the wait is the only thing worth acting on from a wall of panes. The pane reports the agent's driver rather than each turn: the harness chains turns through a pending inbox inside one driver run, and reporting each turn's end would read as done between two turns of an agent that is still working. Reports are sequenced per source, so a delivery that arrives late cannot undo the state the surface already moved past, and a state Herdr is already showing is not sent again. A report is only counted as made when Herdr acknowledges it: one that failed is tried again — soon after, then with a growing wait — and a session identity Herdr never confirmed travels with the next report of any kind. The retry cannot wait for another state change, because the pane may have nothing left to say: a driver that stopped while the socket was down produces no further event. States still waiting to be sent are collapsed into the newest one, so a socket that was down for a minute is told where the pane is rather than where it has been. The release carries the next number in that same sequence for the same reason: Herdr reads one that cannot beat the pane's last report as stale, and a stale release leaves the row waiting on a process that is gone. It also stops reporting first — a claim landing after the release would take the row back for a process that is leaving — and the report already on the wire is waited for before the row goes back, because Herdr ignores the release of a pane nothing has claimed yet and that late report would then claim it. What is still waiting behind it is dropped rather than sent.
 
 Herdr persists a session reference only for its own built-in integrations, so this pane's session identity travels as metadata tokens instead: a script or a companion plugin reads them back with `herdr pane get <id>` and resumes that exact conversation with `dsh --profile tui --resume=<id>`. Herdr holds a token value up to 80 characters and shortens anything longer, so a session id or directory that cannot be sent whole has its token cleared instead: a shortened path would read as a different directory, and a pane must not claim one. What Herdr cannot do is identify the process itself — its detection table and its screen rules both name built-in agents only — so a pane that has not reported yet reads as an ordinary pane, and is not yet a target: `herdr agent wait` on it fails with `agent_not_found` until the first report lands. Herdr 0.9.1 also keeps the title that accompanies a `blocked` state without showing it anywhere, so a reader sees the state and reads the card on screen.
 
@@ -688,6 +789,9 @@ node tools/pty-drive.mjs --home "$S" --prompt 'Reply with exactly: pong'
 
 Test specs import plugin sources through the `@/` alias. Under this test runner the spec file is resolved with a root-relative id, so parent-relative imports (`../src/...`) do not resolve; the alias and its matching `tsconfig.test.json` path mapping avoid that.
 
+The development guide — the gate, the dogfood script, and the difference between
+a fresh home, a cloned home, and the real one — is [DEVELOPMENT.md](DEVELOPMENT.md).
+
 ## Manual acceptance
 
 The automated checks drive a real PTY, but they run on this machine's terminal. These are the checks only a terminal on your desk can answer; each line is what to do and what it should look like.
@@ -708,6 +812,12 @@ The automated checks drive a real PTY, but they run on this machine's terminal.
 | `dsh-tui: { subcalls: collapsed }` in `$DSH_HOME/settings.yaml`, then a PTC turn | the card arrives alone, and editing the document to `inline` draws the one-line calls in a running session |
 | a thought, folded | a click on the row opens the thought under its summary; a click on the body folds it back, and the other thoughts keep their own state |
 | a bash card, then a click on it | the row opens to its command, its retained output, and its exit status; a click folds it back to one row |
+| a bash command that exits non-zero | the same row as any other failure: the tool's name in the failed colour, with the `exit 1` it ended on |
+| a call that runs for more than a second, watched while it runs | its name is drawn in the running colour with `~1s` counting up at the end of the row, the command still on it; both give way to the measured facts the moment the result lands |
+| a PTC turn with several dispatched calls, one of them slow, one of them exiting non-zero | the call still in flight names itself in the running colour, the one that exited non-zero is red with its `exit 1`, and the rest are plain with their own outcome |
+| a PTC turn whose program ran for more than a second | the card's row counts the seconds while it runs; once the program answers, the total stays on the row dimmed and italic |
+| `dsh-tui: { tokens: { tool.running.title: { hidden: true } } }` in `$DSH_HOME/settings.yaml`, then a slow call | the name is drawn in the colour a settled call uses and the seconds still count, and the call still settles into its result |
+| `dsh-tui: { tokens: { tool.running.elapsed: { hidden: true } } }`, then a slow call | the row keeps its running colour and reports no duration |
 | a call that failed, then a click on its card | the card opens to the reason it failed — the same words the model was shown — and a click folds it back |
 | `dsh-tui: { tools: { bash: { output: tail, tail: 5 } } }`, then a bash run | the folded row keeps the last five output rows and counts the rest |
 | `dsh-tui: { tools: { read: { collapsed: false } } }`, then a read | the card starts open; folded on a narrow terminal, the path gives up room first and the row stops short of the edge |
@@ -734,6 +844,8 @@ The automated checks drive a real PTY, but they run on this machine's terminal.
 | a 40-column terminal | transcript and card rows end in `…` instead of wrapping into the next line |
 | a question with a long option at 40 columns | the option wraps onto rows indented under its label, and `0. other — type your own answer` sits under the list |
 | press `0` on a question, type an answer, press Enter | the editor under row `0` shows the text as it is edited, and the model receives it as that question's answer |
+| a question with no options, then type `/` | no menu opens and the slash stays part of the answer: answers are text the model reads, so the commands this session can run are offered only in the prompt bar |
+| the same question, then type `@` and a fragment | the workspace's files are offered under the answer, and the menu's own keys pick a row instead of answering the question |
 | type a prompt without sending it, then answer a question | the prompt bar steps aside while the question is open and holds the same prompt again afterwards |
 | `echo hi \| dsh --profile tui` | refuses with a non-zero exit and a message naming the TTY requirement |
 | `/stash`, `/stash-pop` in one terminal | the footer shows `stash 1` after the stash and the draft returns to the editor after the pop |
@@ -758,9 +870,11 @@ The workflow stores no npm token: the registry trusts `release.yml` on the `npm-
 
 - Two different things are called a preset. The agent mode (`--preset`, `/preset`) is fixed once a session has produced a turn; the permission preset (`/permission <preset>`, named in the status line) can change at any time.
 - `/model` changes the route and reasoning effort for the running session only. Catalog membership is advisory — an adapter may accept an id it does not advertise, while an explicit effort is checked against the route's own levels before it is applied. The picker offers the routes this deployment configured, not the ones it can prove credentialed: a provider whose key or sign-in is still missing appears like any other, and its first request names the missing credential.
+- Model discovery failures show a safe notice. Healthy provider catalogs remain selectable. Check provider configuration and credentials before retrying `/model`.
 - Scrolling is the mouse wheel, or the terminal's own scrollback keys where it offers them.
 - A turn that ran longer than ten seconds rings the terminal bell when it ends, because the reader may have walked away; `--no-bell` turns that off.
 - The dock shows the goal, plan mode, the todo items still to do, and any background job or delegation still running; a settled item leaves rather than turns into a completed row, and the list clears when the next turn opens so a fresh task never inherits the previous one's checklist. The transcript marks where older history was compacted away. `/plan` toggles plan mode; `/plan <message>` also steers that message, which is the base command's own behaviour.
+- The dock shows three running subagents by default. When more than three run, click the heading, overflow row, or blank cells in that section to show all. Click again to show three. Click a child’s text to view its transcript. Press `ctrl+b` to return.
 - Background jobs and subagent runs are live process state, not durable events: they disappear when the run ends, and a resumed session starts with an empty board and roster.
 - A card reads its tool's own render intent through the agent whose session is on screen, so a stored session with no live agent — one this process is not running, or a child that has already finished — folds to the generic card instead of the tool's own.
 - Reading a child's conversation does not move the terminal: commands, approvals, and the status line stay with the session you launched, and the transcript is the only thing that switches. The status line carries the way back, read from the map in force, so a remap shows up without reopening the view.
@@ -784,7 +898,7 @@ discipline as this one.
 | Plugin | What it adds |
 |---|---|
 | [`@sagmans/dsh-auto-compact`](https://github.com/sagmans/dsh-auto-compact) | An absolute token trigger for automatic compaction: the conversation condenses at `min(thresholdTokens, contextWindow × thresholdRatio)` instead of the window ratio alone, so a large-window model pays a fixed price, with per-route overrides. Its patch swaps the shipped `compaction-basic` backend — the same row this bundle already takes out of the global composition — so the profile still keeps exactly one compaction service, and this surface needs no setting for it. |
-| [`@sagmans/dsh-provider-extra`](https://github.com/sagmans/dsh-provider-extra) | Extra provider routes: OpenCode Go, which sends the live conversation id in `x-opencode-session` for routing and prompt caching, and OpenAI Codex over a ChatGPT subscription's OAuth flow with the harness credential store. Its routes join the `/model` picker like every configured provider. |
+| [`@sagmans/dsh-provider-extra`](https://github.com/sagmans/dsh-provider-extra) | Extra provider routes: OpenCode Go, which sends the live conversation id in `x-opencode-session` for routing and prompt caching, and OpenAI Codex over a ChatGPT subscription's OAuth flow with the harness credential store. Its routes join the `/model` picker like every configured provider. TUI also works without this package, using the core `llm` and `agentDefaultModel` services. |
 
 ```sh
 dsh plugin --profile tui add @sagmans/dsh-auto-compact