@aiwayds/dsh-tui-pi 2.21.0 → 2.23.0

package/lib/theme-settings.d.ts

@@ -1,37 +1,51 @@
 /**
- * Theme settings: persists the user's theme preference, the think/tool panel
- * height, and the subagent concurrency/rounds limits under the `dsh-tui`
- * settings namespace, surfaced by the /settings browser and the /theme
- * command. The theme and panel-height preferences are read once at TUI
- * startup (`readThemePreference` / `readPanelHeightPreference`); the subagent
- * limits are read live at every policy decision (`readSubagentLimits`). The
- * namespace is marked `applies: 'live'`: a committed change (the /theme
- * picker, the /settings browser, an external edit) is pushed through the
- * watch hook, so the running TUI repaints without a restart.
+ * Theme settings: the dsh-tui entry configuration — the user's theme
+ * preference, the think/tool panel height, the UI language, the footer-hint
+ * selection, the icon-set mode and the subagent concurrency/rounds limits.
  *
- * The session-management sections (`retention`, `resume`) ride the same
- * namespace but are read from the descriptor's USER layer
- * (`readSessionManagementExplicit`), not the resolved value: only a field
- * the user explicitly wrote to settings.yaml is an override — the resolved
- * value's baked-in defaults must not shadow the DSH_TUI_RETENTION_* /
- * DSH_TUI_RESUME_* environment variables (precedence: settings explicit >
- * env > default; the janitor consumes its values at next startup, the
- * /resume filter at every picker open).
+ * dsh 0.1.7 model (breaking change from 0.1.5): the runtime
+ * namespace-registration API is GONE. A plugin declares its
+ * user-facing configuration as a `static Config` schema; the loader projects
+ * every `.volatile()` field into the settings surface (describe / update /
+ * mutate) and hands the resolved values to `apply(ctx, config)` — volatile
+ * fields arrive as live `Volatile<T>` references. Declaration IS
+ * registration: there is nothing to register at runtime anymore.
+ *
+ * Reading: `config.field.get()` — a deep-frozen snapshot, refreshed IN PLACE
+ * by the loader on every volatile-only commit (the fiber never remounts, the
+ * references stay identical), so a value read is always current.
+ *
+ * Hot-apply: the plugin subscribes to `settings/document-updated` (the
+ * 0.1.5 per-namespace watch-hook replacement) and re-reads the references on
+ * every event. The
+ * event also fires for this TUI's own writes; every sink downstream is an
+ * idempotent no-op on an unchanged value (theme-bundle identity guard, same
+ * height, same hints), so the echo is harmless.
+ *
+ * Session-management sections (`retention`, `resume`, `askUser`) keep their
+ * USER-layer precedence seam: only a field the user explicitly wrote into the
+ * profile patch (`cordis.patch.yml` → entry `dsh-tui` → `config:`; the 0.1.5
+ * `settings.yaml` document is auto-imported there once on first 0.1.7 boot)
+ * is an override — the resolved value's baked-in defaults must not shadow the
+ * DSH_TUI_RETENTION_* / DSH_TUI_RESUME_* / DSH_TUI_ASK_USER_* environment
+ * variables (precedence: settings explicit > env > default). Those readers
+ * go through `settings.describe()[].user`, the only channel exposing the raw
+ * explicit layer.
  */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Context, Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 import { type FooterHints } from './footer.ts';
 import { type PanelHeight } from './activity.ts';
 import type { IconSet } from './icons.ts';
 import type { ThemePreference } from './theme/index.ts';
 /**
- * Settings namespace carrying the persisted dsh-tui preferences.
+ * Settings entry id carrying the persisted dsh-tui preferences.
  *
- * dsh-settings 0.1.2-alpha.3 removed the runtime settingsNamespace() helper
- * (and the SettingsNamespace constructor it returned): a plain literal is the
- * supported spelling — register() brand-checks it at the type level
- * (SettingsNamespaceInput) and validates the same lowercase-hyphenated pattern
- * at runtime (parseSettingsNamespace). Comparisons against a descriptor's
- * branded `ns` stay exact string equality.
+ * This is BOTH the profile patch entry id (cordis.patch.yml mounts this
+ * package as `- id: dsh-tui`) and the legacy settings.yaml section name —
+ * keeping them identical is what lets the 0.1.7 one-time settings.yaml
+ * import (`settings.yaml` → renamed `.imported`, sections merged into the
+ * matching entry's config) pick up every existing user value without a shim.
  */
 export declare const THEME_SETTINGS_NAMESPACE = "dsh-tui";
 /**
@@ -83,108 +97,273 @@ export interface SubagentLimits {
     registeredOnly: boolean;
 }
 /**
- * Default subagent limits, applied whenever the settings service, namespace,
- * or a field cannot be read. 4 concurrent children and 75 rounds per child
- * are the documented out-of-the-box behavior (75 rounds = 75 LLM
- * round-trips, headroom for heavy delegated tasks while still capping a
- * runaway child); the native `subagent` tool is disabled by default — the
- * TUI's user delegates through registered agents (toggle it in /agents → l
- * limits when the plain tool is needed again).
+ * Default subagent limits, applied whenever the entry config cannot be read.
+ * 4 concurrent children and 75 rounds per child are the documented
+ * out-of-the-box behavior (75 rounds = 75 LLM round-trips, headroom for heavy
+ * delegated tasks while still capping a runaway child); the native `subagent`
+ * tool is disabled by default — the TUI's user delegates through registered
+ * agents (toggle it in /agents → l limits when the plain tool is needed again).
  */
 export declare const DEFAULT_SUBAGENT_LIMITS: SubagentLimits;
+/** Grouped session-log retention knobs (see resolveRetentionConfig). */
+export interface RetentionSettings {
+    maxCount: number;
+    maxAgeDays: number;
+    minIdleHours: number;
+}
+/** Grouped /resume display-window knobs. */
+export interface ResumeSettings {
+    maxAgeDays: number;
+    minBytes: number;
+}
+/** Grouped ask-user auto-answer timeout knobs. */
+export interface AskUserSettings {
+    idleMinutes: number;
+    absoluteMinutes: number;
+}
 /**
- * Register the `dsh-tui` settings namespace with the settings provider.
- *
- * This registers directly through the provider (not through a
- * section-install helper): the registration rides the scoped injection fiber
- * and disappears with the settings service. `onPreferenceChange`, when given,
- * receives every committed change (including this TUI's own writes) through
- * the scope's watch hook; callers guard re-applies by theme-bundle identity
- * and height change, so an echoed self-write is a no-op. No source thunk is
- * needed — the read helpers read the resolved values on demand at TUI
- * startup.
+ * Runtime face of the `dsh-tui` entry config. Every field is `.volatile()` —
+ * user-editable through the settings surface and hot-applied without a
+ * plugin remount — so each arrives as a live `Volatile<T>` reference, read
+ * with `.get()`.
+ */
+export interface TuiSettings {
+    language: Volatile<string>;
+    theme: Volatile<ThemePreference>;
+    panelHeight: Volatile<PanelHeight>;
+    maxAgents: Volatile<number>;
+    maxRounds: Volatile<number>;
+    maxRoundsGrace: Volatile<number>;
+    disableSubagent: Volatile<boolean>;
+    registeredOnly: Volatile<boolean>;
+    footerHints: Volatile<FooterHints>;
+    cacheHitMode: Volatile<CacheHitMode>;
+    iconSet: Volatile<IconSet>;
+    rememberPreset: Volatile<boolean>;
+    favoriteModels: Volatile<string[]>;
+    hiddenModels: Volatile<string[]>;
+    retention: Volatile<RetentionSettings>;
+    resume: Volatile<ResumeSettings>;
+    askUser: Volatile<AskUserSettings>;
+}
+/**
+ * The `dsh-tui` entry Config schema — the whole settings surface. Exported
+ * from the plugin root (src/index.ts re-exports it): the loader reads
+ * `plugin.Config` off the module namespace and validates + resolves the
+ * entry's config against it; every field is `.volatile()`, so the settings
+ * browser lists all of them and a legacy settings.yaml `dsh-tui:` section
+ * imports wholesale (an import carrying any non-volatile field would be
+ * rejected as a whole).
  *
- * @param ctx - plugin context; does nothing while no settings service is mounted.
- * @param onPreferenceChange - hot-reload sink for committed `dsh-tui` theme,
- * panel-height, footer-hints, icon-set and language changes; `undefined` when the
- * namespace is already registered (a reloaded plugin instance, a second mount
- * of this bundle) or registration fails.
+ * Plain z.number() (not z.natural()) inside `retention`/`resume`/`askUser` on
+ * purpose, same as the 0.1.5 schema: a range-constrained field lets one
+ * hand-edited out-of-range number get the whole volatile-only update refused
+ * (the write is rejected and the raw value still lands on disk — see the
+ * dsh 0.1.7 "not volatile / validation" semantics), so the per-field range
+ * check happens in the readers (resolveRetentionConfig / resolveResumeConfig /
+ * resolveAskUserTimeouts), which fall back to env/defaults with one stderr
+ * line instead.
+ */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    language: z<string, string, "volatile-defined">;
+    theme: z<string, string, "volatile-defined">;
+    panelHeight: z<"1" | "5" | "7" | "10" | "all", "1" | "5" | "7" | "10" | "all", "volatile-defined">;
+    maxAgents: z<number, number, "volatile-defined">;
+    maxRounds: z<number, number, "volatile-defined">;
+    maxRoundsGrace: z<number, number, "volatile-defined">;
+    disableSubagent: z<boolean, boolean, "volatile-defined">;
+    registeredOnly: z<boolean, boolean, "volatile-defined">;
+    footerHints: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        send: z<boolean, boolean, "defined">;
+        stop: z<boolean, boolean, "defined">;
+        quit: z<boolean, boolean, "defined">;
+        quitEmpty: z<boolean, boolean, "defined">;
+        subagents: z<boolean, boolean, "defined">;
+        search: z<boolean, boolean, "defined">;
+        history: z<boolean, boolean, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        send: z<boolean, boolean, "defined">;
+        stop: z<boolean, boolean, "defined">;
+        quit: z<boolean, boolean, "defined">;
+        quitEmpty: z<boolean, boolean, "defined">;
+        subagents: z<boolean, boolean, "defined">;
+        search: z<boolean, boolean, "defined">;
+        history: z<boolean, boolean, "defined">;
+    }>>>, "volatile-defined">;
+    cacheHitMode: z<"session" | "lastMessage", "session" | "lastMessage", "volatile-defined">;
+    iconSet: z<"auto" | "plain" | "nerdfont", "auto" | "plain" | "nerdfont", "volatile-defined">;
+    rememberPreset: z<boolean, boolean, "volatile-defined">;
+    favoriteModels: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    hiddenModels: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    retention: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        maxCount: z<number, number, "defined">;
+        maxAgeDays: z<number, number, "defined">;
+        minIdleHours: z<number, number, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        maxCount: z<number, number, "defined">;
+        maxAgeDays: z<number, number, "defined">;
+        minIdleHours: z<number, number, "defined">;
+    }>>>, "volatile-defined">;
+    resume: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        maxAgeDays: z<number, number, "defined">;
+        minBytes: z<number, number, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        maxAgeDays: z<number, number, "defined">;
+        minBytes: z<number, number, "defined">;
+    }>>>, "volatile-defined">;
+    askUser: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        idleMinutes: z<number, number, "defined">;
+        absoluteMinutes: z<number, number, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        idleMinutes: z<number, number, "defined">;
+        absoluteMinutes: z<number, number, "defined">;
+    }>>>, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    language: z<string, string, "volatile-defined">;
+    theme: z<string, string, "volatile-defined">;
+    panelHeight: z<"1" | "5" | "7" | "10" | "all", "1" | "5" | "7" | "10" | "all", "volatile-defined">;
+    maxAgents: z<number, number, "volatile-defined">;
+    maxRounds: z<number, number, "volatile-defined">;
+    maxRoundsGrace: z<number, number, "volatile-defined">;
+    disableSubagent: z<boolean, boolean, "volatile-defined">;
+    registeredOnly: z<boolean, boolean, "volatile-defined">;
+    footerHints: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        send: z<boolean, boolean, "defined">;
+        stop: z<boolean, boolean, "defined">;
+        quit: z<boolean, boolean, "defined">;
+        quitEmpty: z<boolean, boolean, "defined">;
+        subagents: z<boolean, boolean, "defined">;
+        search: z<boolean, boolean, "defined">;
+        history: z<boolean, boolean, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        send: z<boolean, boolean, "defined">;
+        stop: z<boolean, boolean, "defined">;
+        quit: z<boolean, boolean, "defined">;
+        quitEmpty: z<boolean, boolean, "defined">;
+        subagents: z<boolean, boolean, "defined">;
+        search: z<boolean, boolean, "defined">;
+        history: z<boolean, boolean, "defined">;
+    }>>>, "volatile-defined">;
+    cacheHitMode: z<"session" | "lastMessage", "session" | "lastMessage", "volatile-defined">;
+    iconSet: z<"auto" | "plain" | "nerdfont", "auto" | "plain" | "nerdfont", "volatile-defined">;
+    rememberPreset: z<boolean, boolean, "volatile-defined">;
+    favoriteModels: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    hiddenModels: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
+    retention: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        maxCount: z<number, number, "defined">;
+        maxAgeDays: z<number, number, "defined">;
+        minIdleHours: z<number, number, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        maxCount: z<number, number, "defined">;
+        maxAgeDays: z<number, number, "defined">;
+        minIdleHours: z<number, number, "defined">;
+    }>>>, "volatile-defined">;
+    resume: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        maxAgeDays: z<number, number, "defined">;
+        minBytes: z<number, number, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        maxAgeDays: z<number, number, "defined">;
+        minBytes: z<number, number, "defined">;
+    }>>>, "volatile-defined">;
+    askUser: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+        idleMinutes: z<number, number, "defined">;
+        absoluteMinutes: z<number, number, "defined">;
+    }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+        idleMinutes: z<number, number, "defined">;
+        absoluteMinutes: z<number, number, "defined">;
+    }>>>, "volatile-defined">;
+}>>, "plain">;
+/**
+ * Bind the loader-resolved entry config (the `config` parameter of
+ * `apply(ctx, config)`). Called once per plugin application; a `/reload`
+ * re-runs `apply` and re-binds. Volatile-only commits later swap the values
+ * behind the SAME references in place, so the bound object stays current
+ * without rebinding.
  */
-export declare function registerThemeSettings(ctx: Context, onPreferenceChange?: (pref: ThemePreference, panelHeight: PanelHeight, footerHints: FooterHints, iconSet: IconSet, language: string) => void): void;
+export declare function bindTuiConfig(config: TuiSettings | undefined): void;
+/** Resolve an export of the Config schema into a `TuiSettings`-shaped object (test helper). */
+export declare function resolveTuiSettings(overrides?: Record<string, unknown>): TuiSettings;
 /** Validate an unknown `language` value (anything else narrows to the 'en' fallback). */
 export declare function narrowLanguage(value: unknown): string;
+/**
+ * Subscribe the hot-reload sink to committed `dsh-tui` changes — the 0.1.7
+ * replacement of the 0.1.5 watch hook (the runtime registration call itself
+ * is gone: the static Config schema declares the entry config, the loader
+ * owns the projection).
+ *
+ * `settings/document-updated` carries `(ns, revision)` and fires whenever the
+ * entry's raw config changed — the /theme picker, the /settings browser, an
+ * external patch edit, or this TUI's own write (the echo). The handler
+ * re-reads the live volatile references (the loader updated them in place
+ * before the event) and forwards the narrowed bundle to the sink; callers
+ * guard re-applies by theme-bundle identity and height change, so an echoed
+ * self-write is a no-op. The whole commit → references → event → `.get()`
+ * → sink chain is synchronous per event.
+ *
+ * @param ctx - plugin context; the subscription dies with the plugin fiber.
+ * @param onPreferenceChange - hot-reload sink for committed `dsh-tui` theme,
+ * panel-height, footer-hints, icon-set and language changes; `undefined`
+ * registers nothing.
+ */
+export declare function subscribeThemeSettings(ctx: Context, onPreferenceChange?: (pref: ThemePreference, panelHeight: PanelHeight, footerHints: FooterHints, iconSet: IconSet, language: string) => void): void;
 /**
  * Read the persisted theme preference (the startup snapshot).
  *
- * @param ctx - plugin context.
- * @returns the resolved `dsh-tui` theme value, or `'auto'` when the settings
- * service is absent or the namespace/value cannot be read.
+ * @returns the live `dsh-tui` theme value, or `'auto'` when the entry config
+ * is not bound (a `Config`-less deployment always has the schema default).
  */
-export declare function readThemePreference(ctx: Context): Promise<ThemePreference>;
+export declare function readThemePreference(_ctx: Context): ThemePreference;
 /**
  * Read the persisted think/tool panel height (the startup snapshot).
  *
- * @param ctx - plugin context.
- * @returns the resolved `dsh-tui` panelHeight value, or DEFAULT_PANEL_HEIGHT
- * when the settings service is absent or the namespace/value cannot be read.
+ * @returns the live `dsh-tui` panelHeight value, or DEFAULT_PANEL_HEIGHT when
+ * the entry config is not bound.
  */
-export declare function readPanelHeightPreference(ctx: Context): Promise<PanelHeight>;
+export declare function readPanelHeightPreference(_ctx: Context): PanelHeight;
 /**
  * Read the persisted footer-hint selection (the startup snapshot).
  *
- * @param ctx - plugin context.
- * @returns the resolved `dsh-tui` footerHints object, or DEFAULT_FOOTER_HINTS
- * when the settings service is absent or the namespace/value cannot be read.
+ * @returns the live `dsh-tui` footerHints object, or DEFAULT_FOOTER_HINTS
+ * when the entry config is not bound.
  */
-export declare function readFooterHintsPreference(ctx: Context): Promise<FooterHints>;
+export declare function readFooterHintsPreference(_ctx: Context): FooterHints;
 /**
  * Read the persisted icon-set mode (the startup snapshot).
  *
- * @param ctx - plugin context.
- * @returns the resolved `dsh-tui` iconSet value, or `'auto'` when the settings
- * service is absent or the namespace/value cannot be read.
+ * @returns the live `dsh-tui` iconSet value, or `'auto'` when the entry
+ * config is not bound.
  */
-export declare function readIconSetPreference(ctx: Context): Promise<IconSet>;
+export declare function readIconSetPreference(_ctx: Context): IconSet;
 /**
  * Read the persisted UI language (the startup snapshot).
  *
- * @param ctx - plugin context.
- * @returns the resolved `dsh-tui` language value, or DEFAULT_LANGUAGE ('en')
- * when the settings service is absent or the namespace/value cannot be read.
- * Whether the id is actually installed is decided by the i18n registry
- * (initI18n degrades unknown ids to 'en').
+ * @returns the live `dsh-tui` language value, or DEFAULT_LANGUAGE ('en') when
+ * the entry config is not bound. Whether the id is actually installed is
+ * decided by the i18n registry (initI18n degrades unknown ids to 'en').
  */
-export declare function readLanguagePreference(ctx: Context): Promise<string>;
+export declare function readLanguagePreference(_ctx: Context): string;
 /**
  * Read the persisted preset-memory toggle (the startup snapshot). Default
  * TRUE: remembering is the out-of-the-box behavior; only an explicit
- * `dsh-tui.rememberPreset: false` turns it off.
+ * `rememberPreset: false` turns it off.
  *
- * @param ctx - plugin context.
- * @returns the resolved boolean, or `true` when the settings service is
- * absent or the namespace/value cannot be read.
- */
-export declare function readRememberPreset(ctx: Context): Promise<boolean>;
-/**
- * Read the currently persisted preset-memory toggle, synchronously. Unlike
- * `readRememberPreset` (the startup snapshot), this describes whatever the
- * settings service exposes right now — the /preset switch path calls it at
- * every commit, so a `/settings` toggle applies without a restart.
- * @returns `true` when the service, namespace, or value is absent.
+ * @returns the live boolean, or `true` when the entry config is not bound.
  */
-export declare function currentRememberPreset(ctx: Context): boolean;
+export declare function readRememberPreset(_ctx: Context): boolean;
 /**
- * Explicit session-management overrides as the user wrote them in
- * settings.yaml — the raw `user` layer of the descriptor, NOT the resolved
- * value. This distinction is the precedence seam: the resolved value bakes
- * the schema defaults in (a missing `retention.maxCount` resolves to 100),
- * so reading it would make the defaults outrank the DSH_TUI_RETENTION and
- * DSH_TUI_RESUME environment variables; only a
- * field PRESENT in the user layer is an explicit override
- * (`settings.yaml explicit > env > default`, honored by
- * `resolveRetentionConfig` / `resolveResumeConfig`). Fields stay `unknown`
- * — a hand-edited document can carry anything, and the resolvers narrow
- * per field with one stderr line on garbage.
+ * Explicit session-management overrides as the user wrote them into the
+ * profile patch (entry `dsh-tui` → `config:`) — the raw `user` layer of the
+ * settings descriptor, NOT the resolved value. This distinction is the
+ * precedence seam: the resolved value bakes the schema defaults in (a missing
+ * `retention.maxCount` resolves to 100), so reading it would make the
+ * defaults outrank the DSH_TUI_RETENTION and DSH_TUI_RESUME environment
+ * variables; only a field PRESENT in the user layer is an explicit override
+ * (`settings explicit > env > default`, honored by `resolveRetentionConfig` /
+ * `resolveResumeConfig`). Fields stay `unknown` — a hand-edited document can
+ * carry anything, and the resolvers narrow per field with one stderr line on
+ * garbage. The user layer rides `settings.describe()` — the only public
+ * channel for the raw explicit layer (volatile `.get()` reads expose the
+ * RESOLVED value only).
  */
 export interface SessionManagementExplicit {
     retention?: {
@@ -198,27 +377,25 @@ export interface SessionManagementExplicit {
     };
 }
 /**
- * Read the explicit `dsh-tui.retention` / `dsh-tui.resume` sections from
- * the settings document's user layer (see `SessionManagementExplicit`).
- * Awaits the namespace registration bounded (same plumbing as the theme
- * readers), so the startup retention pass can call it without hanging a
- * settings-less deployment.
+ * Read the explicit `dsh-tui.retention` / `dsh-tui.resume` sections from the
+ * settings document's user layer (see `SessionManagementExplicit`).
  *
+ * @param ctx - plugin context.
  * @returns ALWAYS the two-key shape — a section absent from the user
- * layer (or the whole service/namespace missing) reads as
+ * layer (or the whole service/entry missing) reads as
  * `{ retention: undefined, resume: undefined }`, never a bare
  * `undefined`, so callers destructure one stable shape. "Nothing
  * explicitly configured" (env/defaults govern) and "nothing to read at
  * all" are the same outcome for every consumer.
  */
-export declare function readSessionManagementExplicit(ctx: Context): Promise<SessionManagementExplicit>;
+export declare function readSessionManagementExplicit(ctx: Context): SessionManagementExplicit;
 /**
  * Raw user-layer `dsh-tui.askUser` section — the explicit ask-user timeout
- * overrides as written in settings.yaml (see `readSessionManagementExplicit`
- * for why the USER layer, not the resolved value, is the precedence seam:
- * the resolved value's schema defaults must not shadow the
- * DSH_TUI_ASK_USER_* environment variables). `undefined` = nothing
- * explicitly configured (env/defaults govern).
+ * overrides as written into the profile patch (see
+ * `readSessionManagementExplicit` for why the USER layer, not the resolved
+ * value, is the precedence seam: the resolved value's schema defaults must
+ * not shadow the DSH_TUI_ASK_USER_* environment variables). `undefined` =
+ * nothing explicitly configured (env/defaults govern).
  */
 export interface AskUserTimeoutExplicit {
     idleMinutes?: unknown;
@@ -226,70 +403,88 @@ export interface AskUserTimeoutExplicit {
 }
 /**
  * Read the explicit `dsh-tui.askUser` section from the settings document's
- * user layer. Awaits the namespace registration bounded (same plumbing as
- * `readSessionManagementExplicit`), so an ask arriving during startup
- * cannot hang on a settings-less deployment. Returns `undefined` when the
- * section, the user layer, the namespace, or the whole service is absent —
- * "nothing explicitly configured" for the ask-user resolver.
+ * user layer. Returns `undefined` when the section, the user layer, the
+ * entry, or the whole service is absent — "nothing explicitly configured"
+ * for the ask-user resolver.
+ */
+export declare function readAskUserExplicit(ctx: Context): AskUserTimeoutExplicit | undefined;
+/**
+ * Read the currently persisted footer-hint selection, synchronously — the
+ * live volatile reference, so a committed change applies on the next read.
+ * @returns DEFAULT_FOOTER_HINTS when the entry config is not bound.
  */
-export declare function readAskUserExplicit(ctx: Context): Promise<AskUserTimeoutExplicit | undefined>;
+export declare function currentFooterHints(_ctx: Context): FooterHints;
 /**
- * Read the currently persisted footer-hint selection, synchronously.
- * Unlike `readFooterHintsPreference` (the startup snapshot), this does not
- * wait for the namespace registration - it describes whatever the settings
- * service exposes right now, so a caller can honor a live change immediately.
- * @returns DEFAULT_FOOTER_HINTS when the service, namespace, or value is absent.
+ * Read the currently persisted footer CH mode, synchronously — the footer
+ * calls it on every render, so a committed change applies on the next repaint.
+ * @returns DEFAULT_CACHE_HIT_MODE when the entry config is not bound.
  */
-export declare function currentFooterHints(ctx: Context): FooterHints;
+export declare function currentCacheHitMode(_ctx: Context): CacheHitMode;
 /**
- * Read the currently persisted footer CH mode, synchronously. Unlike a
- * startup snapshot, this describes whatever the settings service exposes
- * right now — the footer calls it on every render, so a committed change
- * (the /settings browser, an external edit) applies on the next repaint.
- * @returns DEFAULT_CACHE_HIT_MODE when the service, namespace, or value is absent.
+ * Read the currently persisted theme preference, synchronously — the /theme
+ * picker preselects the live value.
+ * @returns 'auto' when the entry config is not bound.
  */
-export declare function currentCacheHitMode(ctx: Context): CacheHitMode;
+export declare function currentThemePreference(_ctx: Context): ThemePreference;
 /**
- * Read the currently persisted theme preference, synchronously.
- * Unlike `readThemePreference` (the startup snapshot), this does not wait for
- * the namespace registration — it describes whatever the settings service
- * exposes right now, so the `/theme` picker preselects the live value, which
- * may have changed since startup (e.g. through the /settings browser).
- * @returns 'auto' when the service, namespace, or value cannot be read.
+ * Read the currently persisted preset-memory toggle, synchronously — the
+ * /preset switch path calls it at every commit, so a `/settings` toggle
+ * applies immediately.
+ * @returns `true` when the entry config is not bound.
  */
-export declare function currentThemePreference(ctx: Context): ThemePreference;
+export declare function currentRememberPreset(_ctx: Context): boolean;
 /**
- * Persist the theme preference to the `dsh-tui` settings namespace. The
- * namespace is `applies: 'live'`, so the commit (observed through the
- * registration's watch hook) hot-applies the change to the running TUI.
+ * Persist the theme preference to the `dsh-tui` entry config. Volatile-only
+ * write: the commit hot-applies to the running TUI through the
+ * `settings/document-updated` subscription.
  * @returns undefined on success, the failure message otherwise.
  */
 export declare function writeThemePreference(ctx: Context, pref: ThemePreference): Promise<string | undefined>;
 /**
- * Persist the UI language to the `dsh-tui` settings namespace. The namespace
- * is `applies: 'live'`, so the commit (observed through the registration's
- * watch hook) hot-applies the language to the running TUI.
+ * Persist the UI language to the `dsh-tui` entry config. Volatile-only
+ * write: the commit hot-applies to the running TUI.
  * @returns undefined on success, the failure message otherwise.
  */
 export declare function writeLanguagePreference(ctx: Context, id: string): Promise<string | undefined>;
 /**
- * Read the currently resolved subagent limits, synchronously. Unlike the
- * startup-snapshot readers, this does not wait for the namespace registration
- * — it describes whatever the settings service exposes right now, so every
- * policy decision (the guard at each spawn, `onRoundCount` at each child
- * assistant message)
- * reflects the latest committed value without a watcher. Missing settings
- * service or namespace, or a non-integer/negative field, degrades to the
- * defaults — a settings-less deployment keeps the documented caps.
+ * Read the currently resolved subagent limits, synchronously — the live
+ * volatile references, so every policy decision (the guard at each spawn,
+ * `onRoundCount` at each child assistant message) reflects the latest
+ * committed value without a watcher. An unbound entry config or a
+ * non-integer/negative field degrades to the defaults — a config-less
+ * deployment keeps the documented caps.
+ */
+export declare function readSubagentLimits(_ctx: Context): SubagentLimits;
+/**
+ * The OFFICIAL dsh-subagent plugin's own caps (dsh 0.1.7: `static Config`
+ * with volatile `maxActiveSubagents` — concurrent continuable children,
+ * default 8 — and `maxDepth` — default delegation depth, default 1). These
+ * are the host-side concurrency/depth limits that compose with — and are
+ * independent of — this TUI's own maxAgents/maxRounds policy knobs. This
+ * reader is DISPLAY-ONLY (the /agents limits panel shows the currently
+ * effective official caps; editing them belongs to /settings, which owns
+ * the `subagent` entry).
+ */
+export interface OfficialSubagentLimits {
+    /** Live official concurrent-children cap; undefined = entry not readable. */
+    maxActiveSubagents: number | undefined;
+    /** Live official delegation depth; undefined = entry not readable. */
+    maxDepth: number | undefined;
+}
+/**
+ * Read the official `subagent` entry's resolved config through the settings
+ * forms descriptor (the only public channel for ANOTHER entry's live
+ * values). Best-effort: no settings service, no such entry, or a malformed
+ * value reads as `undefined` per field — the panel then annotates the row
+ * instead of showing a number it cannot vouch for.
  */
-export declare function readSubagentLimits(ctx: Context): SubagentLimits;
+export declare function readOfficialSubagentLimits(ctx: Context): OfficialSubagentLimits;
 /**
  * Persist one subagent policy knob (maxAgents, maxRounds, or disableSubagent)
- * to the `dsh-tui` settings namespace. The namespace is `applies: 'live'`, so
- * the commit hot-applies without a restart — the policy reads
- * `readSubagentLimits` at the next decision point. Never throws: a deployment
- * without the settings provider, or an unregistered namespace, surfaces a
- * failure message for the caller.
+ * to the `dsh-tui` entry config. Volatile-only write: the commit hot-applies
+ * without a restart — the policy reads `readSubagentLimits` at the next
+ * decision point. Never throws: a deployment without the settings service
+ * surfaces a failure message for the caller.
  * @returns undefined on success, the failure message otherwise.
  */
 export declare function writeSubagentLimit(ctx: Context, key: 'maxAgents' | 'maxRounds' | 'maxRoundsGrace' | 'disableSubagent' | 'registeredOnly', value: number | boolean): Promise<string | undefined>;
@@ -301,17 +496,16 @@ export interface ModelPrefs {
     hiddenModels: string[];
 }
 /**
- * Read the persisted model favorites/hiddens (the startup snapshot). Both
- * lists narrow through `narrowStringList` — a malformed or missing field
- * degrades to an empty list.
+ * Read the persisted model favorites/hiddens. Both lists narrow through
+ * `narrowStringList` — a malformed field degrades to an empty list.
  */
-export declare function readModelPrefs(ctx: Context): Promise<ModelPrefs>;
+export declare function readModelPrefs(_ctx: Context): ModelPrefs;
 /**
  * Persist one model pref list (favoriteModels or hiddenModels) to the
- * `dsh-tui` settings namespace via `settings.mutate` (optimistic concurrency,
- * one retry on `SettingsConflictError`) — never a whole-file rewrite. The
- * caller invokes this on every f/h toggle, so each press lands immediately.
- * Best-effort: a deployment without the settings provider surfaces the
+ * `dsh-tui` entry config via `settings.mutate` (optimistic concurrency, one
+ * retry on `SettingsConflictError`) — never a whole-file rewrite. The caller
+ * invokes this on every f/h toggle, so each press lands immediately.
+ * Best-effort: a deployment without the settings service surfaces the
  * failure message; the in-panel state stays session-local either way.
  * @returns undefined on success, the failure message otherwise.
  */