dsh-ssh-tui 0.7.2 → 0.7.3

package/lib/types/platform.d.ts

@@ -22,21 +22,125 @@ export declare function usesProcessIdentity(platform?: NodeJS.Platform): boolean
  * POSIX wants `detached: true` (setsid) so the Host survives the launcher and a
  * hung-up terminal.
  *
- * Windows is the opposite: `detached: true` maps to DETACHED_PROCESS, which
- * gives the Host **no console at all**, and Windows ignores CREATE_NO_WINDOW
- * (what `windowsHide` sets) when DETACHED_PROCESS is present. Every console
- * child the Host then starts — each tool call, every shell, node, git — has to
- * allocate its own console, which is a visible window flashing over the TUI.
- * Dropping `detached` there lets `windowsHide` do its job: the Host gets its
- * own invisible console, and descendants inherit it instead of creating one.
- * The Host still outlives the launcher: Windows does not kill children with
- * their parent, and its console is its own, so closing the user's terminal does
- * not reach it either.
+ * Windows is the opposite, and the trade-off is forced: `detached: true` maps to
+ * DETACHED_PROCESS, and Windows ignores CREATE_NO_WINDOW (what `windowsHide`
+ * sets) when DETACHED_PROCESS is present. Every console child the Host then
+ * starts — each tool call, every shell, node, git — allocates its own console,
+ * which is a visible window flashing over the TUI. So the Host is spawned
+ * non-detached and inherits the launcher's console; descendants inherit it too
+ * instead of creating one.
+ *
+ * The price *was* on the lifecycle side, and it was measured (on the Windows CI
+ * leg by `scripts/tui-mock-probe.mjs --busy`, not reasoned about): libuv assigns
+ * a non-detached child to its global job object, which is created with
+ * KILL_ON_JOB_CLOSE. The launcher died, the job closed, and the Host was
+ * terminated with it — a closed terminal window ended the session's compute.
+ *
+ * This function still returns `detached: false` there, because it describes a
+ * *direct* spawn, and a direct spawn cannot have both properties: Node exposes
+ * `detached` (DETACHED_PROCESS, which makes Windows ignore CREATE_NO_WINDOW) and
+ * `windowsHide`, but not `CREATE_NEW_CONSOLE`. The way out is to not spawn the
+ * Host directly on Windows: {@link hostBootstrapCommand} starts it through the
+ * OS PowerShell, which *can* ask for a new console and hide it. This direct path
+ * stays as the fallback for a Windows box without PowerShell.
  */
 export declare function hostSpawnOptions(platform?: NodeJS.Platform): {
     detached: boolean;
     windowsHide: boolean;
 };
+/**
+ * The Windows PowerShell that ships with the operating system.
+ *
+ * `powershell.exe` and not `pwsh.exe`: the latter is PowerShell 7, an optional
+ * install, while 5.1 is part of Windows 10/11. `%SystemRoot%` is where it lives
+ * (`%windir%` is the legacy spelling of the same thing); when neither is set
+ * there is nothing to find, and the caller falls back to a direct spawn.
+ */
+export declare function windowsPowerShellPath(env?: NodeJS.ProcessEnv): string | undefined;
+/** A PowerShell single-quoted literal; `''` is the only escape inside one. */
+export declare function psQuote(value: string): string;
+/**
+ * Quote one argv array into a Windows command line, the way `CreateProcess`
+ * parses it back (the rule from "Everyone quotes command line arguments the
+ * wrong way"): wrap in double quotes when the argument is empty or contains
+ * whitespace or a quote, double the backslashes that precede a quote, and double
+ * trailing backslashes before the closing quote. `Start-Process -ArgumentList`
+ * joins its array with spaces and adds no quoting of its own, so the line has to
+ * be right before it is handed over — a `DSH_HOME` with a space in it is the
+ * normal case, not the exotic one.
+ */
+export declare function windowsCommandLine(argv: string[]): string;
+/** `-EncodedCommand` wants base64 of UTF-16LE, which is also what dodges quoting. */
+export declare function encodePowerShellCommand(script: string): string;
+/**
+ * The bootstrap script: start the Host with **its own console, hidden**, and
+ * print its pid so the launcher can watch it.
+ *
+ * `Start-Process -WindowStyle Hidden` is the only way to ask for this from a
+ * Node process. It is ShellExecuteEx/CreateProcess with `CREATE_NEW_CONSOLE` and
+ * `SW_HIDE`: the Host gets a console of its own, so closing the user's terminal
+ * no longer takes it down, and that console is invisible, so the tool calls that
+ * inherit it do not flash. `-PassThru` gives the object whose `Id` is printed;
+ * `-RedirectStandardError` keeps the Host's stderr log, which the direct spawn
+ * used to feed through an inherited fd.
+ *
+ * The whole script travels as an encoded command, so nothing in it is ever
+ * re-parsed by a shell.
+ */
+export declare function hiddenConsoleHostScript(options: {
+    execPath: string;
+    argv: string[];
+    /** Where the Host's stderr goes; omitted only in tests. */
+    stderrFile?: string;
+    /** Where the Host's pid is written for the launcher to read. */
+    pidFile: string;
+}): string;
+/**
+ * Set on the Host's environment by the bootstrap below, through
+ * {@link bootstrapEnv}.
+ *
+ * The Host cannot ask whether it has a console of its own — Node exposes no such
+ * question — so the launcher tells it. That is what lets the one build where the
+ * lifecycle promise does not hold (Windows, no PowerShell, direct child) say so
+ * at boot instead of letting the user discover it by closing the window.
+ */
+export declare const TUI_HOST_START_ENV = "DSH_TUI_HOST_START";
+/** Marker value for a Host started with a hidden console of its own. */
+export declare const TUI_HOST_START_BOOTSTRAP = "hidden-console";
+/** The environment the bootstrap hands to the Host: the marker is added here. */
+export declare function bootstrapEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Whether this Host survives its terminal being closed.
+ *
+ * POSIX always does (`setsid`); Windows does exactly when the bootstrap started
+ * it. A Windows Host without the marker is the fallback direct child, which
+ * libuv's `KILL_ON_JOB_CLOSE` job takes down with the launcher — the one case
+ * worth a boot notice.
+ */
+export declare function hostHasOwnConsole(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** How the Host is started when it must not be a direct child. */
+export interface HostBootstrapCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * The hidden-console bootstrap for this platform, or `undefined` when the Host
+ * should be spawned directly.
+ *
+ * Windows only, and only when the OS PowerShell is really there: the caller
+ * falls back to {@link hostSpawnOptions}, which keeps the boot working (without
+ * the survival property) on a machine where PowerShell is missing or blocked.
+ * `exists` is injectable so the decision is assertable on Linux.
+ */
+export declare function hostBootstrapCommand(options: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    exists?: (path: string) => boolean;
+    execPath: string;
+    argv: string[];
+    stderrFile?: string;
+    pidFile: string;
+}): HostBootstrapCommand | undefined;
 /**
  * A path a human can read, with the platform's own shorthand.
  *
@@ -48,3 +152,64 @@ export declare function displayHomePath(home: string, file: string, options?: {
     env?: NodeJS.ProcessEnv;
     userHome?: string;
 }): string;
+/**
+ * Who owns the files this plugin writes, and how to keep it that way.
+ *
+ * On POSIX the `mode` passed to `writeFile`/`mkdir` (`0o600`, `0o700`) is the
+ * whole story. **On Windows it is silently ignored**, and the files that matter
+ * here are not cosmetic: `env.cmd` carries API keys, the SuperGrok token file
+ * carries an OAuth grant, and the lock/socket directories carry session
+ * metadata. What they get instead is the ACL inherited from their parent — fine
+ * under `%USERPROFILE%\.dsh`, and *not* fine when `DSH_HOME` points somewhere
+ * shared (`C:\dsh`, a network share, a machine where `Users` can read the
+ * directory), which is exactly when nobody notices.
+ *
+ * So the intent is applied explicitly: `icacls` with inheritance removed and a
+ * single grant to the current user. The argv is built by a pure function so it
+ * can be asserted on Linux; applying it is best-effort by design — a machine
+ * without `icacls`, or a path held open by another process, must not fail the
+ * write that just succeeded. Failing closed here would mean a TUI that cannot
+ * save its own settings.
+ */
+/**
+ * The account `icacls` should grant, or undefined when the environment has none.
+ *
+ * `%USERDOMAIN%\%USERNAME%` where both are present: on a domain-joined machine a
+ * bare name can resolve to the machine-local account of the same name, and a
+ * grant to the wrong account — with inheritance already removed — would leave
+ * the user's own API keys inaccessible to them.
+ */
+export declare function aclUserName(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;
+/**
+ * The exact `icacls` arguments for one path.
+ *
+ * `/inheritance:r` drops what the parent offered (this is the part that matters:
+ * adding a grant without removing inheritance leaves `Users` in place), and
+ * `(OI)(CI)` makes a directory's grant apply to what is created inside it —
+ * without it every new lock file would need its own call.
+ */
+export declare function restrictPathArgs(path: string, user: string, options?: {
+    directory?: boolean;
+}): string[];
+/** Directories and files whose contents must not be readable by other users. */
+export interface RestrictDeps {
+    /** Runner for `icacls`; injected by tests. Returns true on success. */
+    run?: (command: string, args: string[]) => boolean;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Apply `mode` on POSIX, a single-user ACL on Windows.
+ *
+ * Returns whether the restriction was applied. Never throws: the caller has
+ * already written the file, and a permission call is not worth losing it over.
+ */
+export declare function restrictPathToUser(path: string, options?: {
+    mode: number;
+    directory?: boolean;
+} & RestrictDeps): Promise<boolean>;
+/** Synchronous twin, for the sites that create their file with `openSync`. */
+export declare function restrictPathToUserSync(path: string, options?: {
+    mode: number;
+    directory?: boolean;
+} & RestrictDeps): boolean;

package/lib/types/preset-authoring.d.ts

@@ -20,21 +20,13 @@
  *   every later launch falls back to the default.
  * @module dsh-ssh-tui/preset-authoring
  */
-import { type AgentPreset, type PresetMetadata } from '@deepseek-ai/dsh-agent-presets';
+import { presetDirectory, type AgentPreset, type PresetMetadata } from './preset-compat.js';
+export { presetDirectory };
 /** The id shape discovery accepts; a directory that fails it is skipped. */
 export declare const PRESET_ID_PATTERN: RegExp;
 /** Whether an id would be discovered at all. */
 export declare function validatePresetId(id: string): boolean;
-/**
- * The directory a preset owns.
- *
- * `AgentPreset.path` is the composition file the preset publishes, not the
- * directory, so anything that writes beside it (display metadata) starts here.
- * @param preset - a discovered preset.
- * @returns the absolute preset directory.
- */
-export declare function presetDirectory(preset: AgentPreset): string;
-export type PresetRefusalCode = 'invalid-id' | 'exists' | 'not-found' | 'read-only' | 'system' | 'running' | 'empty-metadata';
+export type PresetRefusalCode = 'invalid-id' | 'exists' | 'not-found' | 'read-only' | 'system' | 'managed' | 'running' | 'empty-metadata';
 export interface PresetRefusal {
     error: PresetRefusalCode;
     /** The id the refusal is about, when it names one. */
@@ -78,9 +70,11 @@ export interface PresetCompositionView {
 }
 /**
  * The authoring subset of the service, feature-detected rather than assumed:
- * the plugin still supports 0.1.2-rc.1, whose `agentPresets` may predate
- * `copy`, `remove`, `read`, and `compositionInventory`. A missing member turns
- * into a clear message instead of a crash.
+ * the two supported lines expose different preset services under the same
+ * `agentPresets` name. 0.1.5's `dsh-agent-presets` carries `copy`, `remove`,
+ * `read` and `compositionInventory`; the 0.1.7 registry
+ * (`dsh-agent-preset-registry`) does not. A missing member turns into a clear
+ * message instead of a crash.
  */
 export interface PresetAuthoringApi {
     readonly authorable?: boolean;

package/lib/types/preset-compat.d.ts

@@ -0,0 +1,58 @@
+/** The optional display-metadata file beside a preset's composition. */
+export declare const METADATA_FILE = "preset.yml";
+/** Display text a preset may publish about itself. */
+export interface PresetMetadata {
+    /** Human-facing name; falls back to the preset id when absent. */
+    readonly name?: string;
+    /** One sentence on what this preset is for. */
+    readonly description?: string;
+    /** Position within its group; lower comes first. */
+    readonly order?: number;
+}
+/** Where a preset's composition came from, on the line that still records it. */
+export type PresetTrust = 'system' | 'user';
+/**
+ * One preset, as much of it as this plugin reads.
+ *
+ * `id`/`name`/`description`/`order`/`broken` are the fields both lines agree on.
+ * `path` (the composition file) and `trust` (the root it was discovered under)
+ * only exist on the 0.1.5 line; every consumer here treats them as optional,
+ * and the authoring paths refuse rather than guess when they are gone.
+ */
+export interface AgentPreset {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly order?: number;
+    readonly broken?: string;
+    /** 0.1.5 line only: absolute path of the preset's agent composition file. */
+    readonly path?: string;
+    /** 0.1.5 line only: trust recorded from the root it was discovered under. */
+    readonly trust?: PresetTrust;
+}
+/**
+ * The directory a preset owns, when the host still exposes one.
+ *
+ * `AgentPreset.path` is the composition file the preset publishes, not the
+ * directory, so anything that writes beside it (display metadata) starts here.
+ * `undefined` on a host that lists declarative presets instead of directories.
+ * @param preset - a discovered preset.
+ * @returns the absolute preset directory, or undefined when there is none.
+ */
+export declare function presetDirectory(preset: AgentPreset): string | undefined;
+/**
+ * Read a preset's display metadata. Every failure degrades to no metadata: a
+ * preset whose display text is missing, malformed, or unreadable still mounts.
+ * @param directory - the preset directory to read `preset.yml` from.
+ * @returns the published name/description/order, or `{}`.
+ */
+export declare function readPresetMetadata(directory: string): Promise<PresetMetadata>;
+/**
+ * Render display metadata as the file's contents.
+ *
+ * Absent fields are omitted rather than written empty, so a preset with no
+ * description does not ship a key that reads as an intentional blank.
+ * @param metadata - the display text to store.
+ * @returns the YAML document, or undefined when there is nothing to store.
+ */
+export declare function renderPresetMetadata(metadata: PresetMetadata): string | undefined;

package/lib/types/preset-picker.d.ts

@@ -9,7 +9,7 @@
  * service — the caller passes what `list()` returned.
  * @module dsh-ssh-tui/preset-picker
  */
-import type { AgentPreset } from '@deepseek-ai/dsh-agent-presets';
+import type { AgentPreset } from './preset-compat.js';
 /** One option as the question dialog wants it, plus the id it stands for. */
 export interface PresetPickerOption {
     id: string;

package/lib/types/preset-rows.d.ts

@@ -19,6 +19,9 @@
  * must never lose the previous content or touch a row the user wrote.
  * @module dsh-ssh-tui/preset-rows
  */
+import type { SettingsGeneration } from './dsh-compat.js';
+/** Which host line the profile being repaired boots on. */
+export type HostGeneration = SettingsGeneration;
 /** One host row the roster block mounts. */
 export interface RosterRow {
     id: string;
@@ -27,13 +30,35 @@ export interface RosterRow {
     config?: readonly string[];
 }
 /**
- * The rows the terminal profile has to mount itself: the roster `/mode` lists,
- * the TypeScript runtime the PTC preset needs, and the host-owned subagent
- * delegation setting.
+ * The rows a 0.1.5 terminal profile has to mount itself: the roster `/mode`
+ * lists, the TypeScript runtime the PTC preset needs, and the host-owned
+ * subagent delegation setting.
  */
 export declare const ROSTER_ROWS: readonly RosterRow[];
+/**
+ * The rows a 0.1.7 terminal profile mounts for itself.
+ *
+ * 0.1.7 deleted the roster this plugin used to list and switch: presets became
+ * per-session declarations a surface mounts (`@deepseek-ai/dsh-agent-preset`
+ * rows over the `agent-preset-registry` service), and `dsh-base` keeps the
+ * agent-plane rows enabled for the TUI, which is single-session and composes
+ * its agent process-wide. What the base does *not* mount are the three rows the
+ * shipped standard preset owns beyond it — the persona prompt, and the
+ * `ask_user_question` / `present` tools — so those are what a TUI profile adds.
+ * Written verbatim as upstream's own `dsh-web-app/presets/standard.patch.yml`
+ * declares them, minus the rows the base already carries.
+ */
+export declare const FORMS_ROWS: readonly RosterRow[];
+/** The rows one host line's profile has to mount. */
+export declare function rosterRows(generation: HostGeneration): readonly RosterRow[];
+/** Every row either line knows about, for name-to-row lookups. */
+export declare const ALL_ROSTER_ROWS: readonly RosterRow[];
 /** The comment header the block introduces itself with, in both writers. */
 export declare const ROSTER_PATCH_HEADER = "# dsh-ssh-tui /mode: the agent-preset roster (standard / minimal / PTC /\n# cordis, plus every preset under $DSH_HOME/.agent-presets) and the two host\n# services the shipped presets need. dsh-base composes no roster in a terminal\n# profile, and a third-party bundle patch may not mount an @deepseek-ai row, so\n# the profile's user layer owns them.\n";
+/** The same header on a host that composes its agent process-wide. */
+export declare const FORMS_PATCH_HEADER = "# dsh-ssh-tui: the agent-plane rows a 0.1.7 terminal profile mounts for itself.\n# That line composes the agent process-wide (presets are a per-session Web\n# feature now), and dsh-base already carries every row the standard preset\n# needs except these three: the persona prompt and the ask_user_question /\n# present tools. The profile's user layer owns them.\n";
+/** The header for one host line. */
+export declare function rosterPatchHeader(generation: HostGeneration): string;
 /** One top-level `- insert:` entry mounting exactly these rows. */
 export declare function rosterInsertEntry(rows: readonly RosterRow[]): string;
 /**
@@ -42,8 +67,23 @@ export declare function rosterInsertEntry(rows: readonly RosterRow[]): string;
  * the same text; a test compares the two so they cannot drift.
  */
 export declare const ROSTER_PATCH_BLOCK: string;
+/** The 0.1.7 block, the same way. */
+export declare const FORMS_PATCH_BLOCK: string;
+/** The block for one host line. */
+export declare function rosterPatchBlock(generation: HostGeneration): string;
 /** The profile patch file the roster block belongs in. */
 export declare function rosterPatchPath(home: string, profile: string): string;
+/**
+ * Whether a profile patch already declares every 0.1.7 agent-plane row.
+ *
+ * Synchronous on purpose: the footer chip is rendered from the main loop and
+ * cannot await a read. The file is small and this runs at startup and after a
+ * repair, not per frame.
+ * @param home - the harness home carrying `profiles/`.
+ * @param profile - the profile to inspect.
+ * @returns whether all three rows are declared (or the row is unreachable).
+ */
+export declare function formsRowsDeclared(home: string, profile: string): boolean;
 /** One row a patch file declares, with enough position to point at it. */
 export interface PatchRowRef {
     /** Insert id, or the target of an override/disable entry. */
@@ -88,7 +128,7 @@ export declare function duplicatePatchRows(rows: readonly PatchRowRef[]): PatchR
 /** Whether a patch already declares one roster row, by id or by module name. */
 export declare function patchNamesRow(rows: readonly PatchRowRef[], row: RosterRow): boolean;
 /** The roster rows a patch does not declare yet. */
-export declare function missingRosterRows(rows: readonly PatchRowRef[]): RosterRow[];
+export declare function missingRosterRows(rows: readonly PatchRowRef[], candidates?: readonly RosterRow[]): RosterRow[];
 export interface PatchRepair {
     text: string;
     /** Roster rows this repair adds, by id. */
@@ -108,10 +148,11 @@ export interface PatchRepair {
  * (the profile template) is replaced; anything else keeps its content and gains
  * a new `- insert:` entry after a blank line.
  * @param existing - the patch file's current text.
- * @param missing - the roster rows to mount; defaults to all of them.
+ * @param missing - the roster rows to mount; defaults to the 0.1.5 set.
+ * @param generation - which host line the profile boots on.
  * @returns the new text, or `undefined` when nothing has to change.
  */
-export declare function planRosterRepair(existing: string, missing?: readonly RosterRow[]): PatchRepair | undefined;
+export declare function planRosterRepair(existing: string, missing?: readonly RosterRow[], generation?: HostGeneration): PatchRepair | undefined;
 /**
  * The patch text with every repeated insert removed, or `undefined` when the
  * file has no duplicate.
@@ -132,10 +173,11 @@ export declare function planDuplicateRepair(existing: string): PatchRepair | und
  * half-written patch would only be seen by the next launch.
  * @param home - the harness home carrying `profiles/`.
  * @param profile - the profile to patch.
- * @param missing - the rows to mount; defaults to the whole roster.
+ * @param missing - the rows to mount; defaults to the 0.1.5 set.
+ * @param generation - which host line the profile boots on.
  * @returns `present` when the row already exists, else `written`.
  */
-export declare function ensureRosterRows(home: string, profile: string, missing?: readonly RosterRow[]): Promise<'present' | 'written'>;
+export declare function ensureRosterRows(home: string, profile: string, missing?: readonly RosterRow[], generation?: HostGeneration): Promise<'present' | 'written'>;
 /**
  * Write a repaired patch next to a copy of the previous content.
  *
@@ -148,4 +190,4 @@ export declare function ensureRosterRows(home: string, profile: string, missing?
  */
 export declare function writePatchWithBackup(path: string, text: string, stamp?: string): Promise<string | undefined>;
 /** The patch text the roster block would produce on its own, for callers that report it. */
-export declare function rosterPatchText(existing: string): string | undefined;
+export declare function rosterPatchText(existing: string, generation?: HostGeneration): string | undefined;

package/lib/types/settings-routes.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Loader row that carries the `/model` route memory as a settings form.
+ *
+ * On the 0.1.5 line `route-memory.ts` registers this namespace itself through
+ * `installSettingsSection`; from 0.1.7 a settings form is projected out of a
+ * loader entry's own `Config` schema, so the same schema is mounted as a row.
+ * The row id (`ssh-tui-routes`, see `cordis.patch.yml`) is the namespace every
+ * read goes through, and it is also the id the host's legacy `settings.yaml`
+ * import lands on, so an existing `ssh-tui-routes` section keeps its routes.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "ssh-tui-settings-routes";
+/** The route-memory section, as the 0.1.7 settings service wants to see it. */
+export declare const Config: import("@deepseek-ai/schemastery").default<import("./route-memory.js").RouteMemorySettings>;
+/** Nothing to mount: the TUI owns every read and write of this section. */
+export declare function apply(_ctx: Context): void;

package/lib/types/settings-subagent.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Loader row that carries the subagent model selection as a settings form.
+ *
+ * On the 0.1.5 line `subagent-model.ts` registers this namespace itself through
+ * `installSettingsSection`; from 0.1.7 a settings form is projected out of a
+ * loader entry's own `Config` schema, so the same schema is mounted as a row.
+ * The row id (`ssh-tui-subagent`, see `cordis.patch.yml`) is the namespace
+ * every read and write goes through, and the id the host's legacy
+ * `settings.yaml` import lands on, so an existing `/submodel` pin survives.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "ssh-tui-settings-subagent";
+/** The subagent selection, as the 0.1.7 settings service wants to see it. */
+export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<{
+    provider: import("@deepseek-ai/schemastery").default<string>;
+    model: import("@deepseek-ai/schemastery").default<string>;
+    reasoningEffort: import("@deepseek-ai/schemastery").default<string>;
+}>, Schemastery.ObjectT<{
+    provider: import("@deepseek-ai/schemastery").default<string>;
+    model: import("@deepseek-ai/schemastery").default<string>;
+    reasoningEffort: import("@deepseek-ai/schemastery").default<string>;
+}>>;
+/** Nothing to mount: the TUI owns every read and write of this section. */
+export declare function apply(_ctx: Context): void;

package/lib/types/subagent-model.d.ts

@@ -129,15 +129,15 @@ export declare function adoptSessionSubagentSelection(ref: SubagentSelectionRef,
  * the built-in default instead.
  */
 export declare function releaseSessionSubagentSelection(ref: SubagentSelectionRef, settingsValue: unknown): void;
-/** Settings schema for `$DSH_HOME/settings.yaml`. */
+/** Settings schema for the subagent selection; every field is form-writable. */
 export declare const SUBAGENT_SETTINGS_SCHEMA: z<Schemastery.ObjectS<{
-    provider: z<string, string>;
-    model: z<string, string>;
-    reasoningEffort: z<string, string>;
+    provider: z<string>;
+    model: z<string>;
+    reasoningEffort: z<string>;
 }>, Schemastery.ObjectT<{
-    provider: z<string, string>;
-    model: z<string, string>;
-    reasoningEffort: z<string, string>;
+    provider: z<string>;
+    model: z<string>;
+    reasoningEffort: z<string>;
 }>>;
 /** Normalize a raw settings section into a live typed selection. */
 export declare function normalizeSubagentSelection(value: unknown): SubagentSelection;

package/lib/types/terminal-caps.d.ts

@@ -0,0 +1,105 @@
+/**
+ * What the terminal in front of us can actually do.
+ *
+ * `color-depth.ts` answers the palette question; this answers the rest of the
+ * ones that change what we may safely emit: mouse reporting, bracketed paste,
+ * the alternate screen, clipboard writes (OSC 52) and hyperlinks (OSC 8), plus
+ * which family of terminal we are talking to.
+ *
+ * Why it is a module and not a few `if`s: these decisions are made from
+ * environment variables that nobody on the team can test by hand for every
+ * desktop — GNOME Terminal, XFCE Terminal, Konsole, xterm, tmux, the Linux
+ * virtual console, Windows Terminal, a legacy Windows console. So the input is
+ * a parameter, the table is data, and `tests/terminal-caps.test.mjs` pins one
+ * fixture per family on any platform.
+ *
+ * The bias is **not** "assume the best". A capability we claim but the terminal
+ * lacks costs the user something real: `?1000h` on a console that cannot report
+ * SGR coordinates swallows its mouse; OSC 52 where nothing reads it makes
+ * `/copy` look like it worked; the alternate screen on a serial console loses
+ * the scrollback. Where a terminal is known to be marginal, the answer is no,
+ * and `DSH_TUI_TERM_CAPS` is the escape hatch for the user who knows better.
+ *
+ * @module dsh-ssh-tui/terminal-caps
+ */
+import { type ColorDepth } from './color-depth.js';
+/** Which terminal implementation is on the other end. */
+export type TerminalFamily = 'windows-terminal' | 'windows-console' | 'vte' | 'konsole' | 'xterm' | 'tmux' | 'screen' | 'linux-console' | 'dumb' | 'unknown';
+/** One terminal's answer to every question this TUI asks of it. */
+export interface TerminalCapabilities {
+    family: TerminalFamily;
+    /** A human name for diagnostics (`/diag`), e.g. `GNOME Terminal (VTE 7000)`. */
+    label: string;
+    colors: ColorDepth;
+    /** Report mouse events at all (`?1000h`). */
+    mouse: boolean;
+    /** Report them as SGR (`?1006h`) instead of the 32-column X10 encoding. */
+    mouseSgr: boolean;
+    /** Report motion while a button is held (`?1002h`), which a drag needs. */
+    mouseDrag: boolean;
+    /** `?2004h`: paste arrives wrapped, so a multi-line paste is one event. */
+    bracketedPaste: boolean;
+    /** `?1049h`: the TUI gets its own screen and restores the scrollback on exit. */
+    alternateScreen: boolean;
+    /** OSC 52 clipboard writes reach the user's own machine. */
+    osc52: boolean;
+    /** OSC 8 hyperlinks are clickable rather than noise. */
+    osc8: boolean;
+    /** OSC 0/2 window-title updates are honoured. */
+    title: boolean;
+    /** `DSH_TUI_TERM_CAPS` tokens that were rejected, for `/diag` to report. */
+    ignoredOverrides: readonly string[];
+}
+/** Everything the classifier reads. `platform` and `env` are injectable. */
+export interface TerminalProbe {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+}
+/** Capability names a user may force on or off through `DSH_TUI_TERM_CAPS`. */
+declare const TOGGLEABLE: readonly ["mouse", "mouseSgr", "mouseDrag", "bracketedPaste", "alternateScreen", "osc52", "osc8", "title"];
+/**
+ * Parse `DSH_TUI_TERM_CAPS`.
+ *
+ * `no-mouse`, `mouse`, `mouse=false` and `mouse = false` all mean what they
+ * look like: the `=` binds first, so the spaced spelling cannot silently invert
+ * into the opposite answer (it did, and `osc52 = false` then *re-enabled* the
+ * clipboard promise). A value outside the two vocabularies, an unknown name or a
+ * bare `no-` is rejected rather than guessed, and the rejects are returned so
+ * `/diag` can show them — this variable is the only feedback channel a user has
+ * when an override does not appear to work.
+ */
+export declare function parseCapsOverrideReport(raw: string): {
+    overrides: Partial<Record<(typeof TOGGLEABLE)[number], boolean>>;
+    ignored: string[];
+};
+/** The overrides alone, for callers that do not report. */
+export declare function parseCapsOverride(raw: string): Partial<Record<(typeof TOGGLEABLE)[number], boolean>>;
+/**
+ * Classify the terminal from the environment.
+ *
+ * Detection is by the markers terminals actually set: Windows Terminal exports
+ * `WT_SESSION`; the VTE family (GNOME Terminal, XFCE Terminal, MATE, Tilix,
+ * Terminator, Guake) exports `VTE_VERSION`; Konsole exports `KONSOLE_VERSION`;
+ * tmux and screen export `TMUX` / `STY` and set a `tmux*` / `screen*` TERM.
+ * Everything else falls back to the TERM name.
+ */
+export declare function detectTerminalFamily(probe?: TerminalProbe): {
+    family: TerminalFamily;
+    label: string;
+};
+/**
+ * Every capability for the terminal in front of us.
+ *
+ * `DSH_TUI_TERM_CAPS` overrides individual answers (`no-mouse`, `osc52=false`);
+ * `DSH_TUI_NO_ALT_SCREEN` and `DSH_TUI_OSC8` keep working because they came
+ * first and are documented.
+ */
+export declare function terminalCapabilities(probe?: TerminalProbe): TerminalCapabilities;
+/** Mouse-tracking sequences to enable, in one write. Empty when unsupported. */
+export declare function mouseEnableSequence(caps: TerminalCapabilities): string;
+/** Mouse-tracking sequences to disable. Always safe to emit: `l` on a mode the
+ *  terminal never enabled is ignored, and leaving a mode on is not. */
+export declare function mouseDisableSequence(): string;
+/** Bracketed-paste enable/disable, or empty when the terminal lacks it. */
+export declare function bracketedPasteSequence(caps: TerminalCapabilities, on: boolean): string;
+export {};