dsh-ssh-tui 0.7.1 → 0.7.3

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/route-memory.d.ts

@@ -5,28 +5,23 @@
 import z from '@deepseek-ai/schemastery';
 import type { Context } from '@deepseek-ai/cordis';
 export declare const ROUTE_MEMORY_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
-/** Settings schema for `$DSH_HOME/settings.yaml` under ssh-tui-routes. */
-export declare const ROUTE_MEMORY_SCHEMA: z<Schemastery.ObjectS<{
-    providers: z<import("@deepseek-ai/cosmokit").Dict<{
-        model?: string | null | undefined;
-        reasoningEffort?: string | null | undefined;
-        updatedAt?: number | null | undefined;
-    } & import("@deepseek-ai/cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        model: z<string, string>;
-        reasoningEffort: z<string, string>;
-        updatedAt: z<number, number>;
-    }>, string>>;
-}>, Schemastery.ObjectT<{
-    providers: z<import("@deepseek-ai/cosmokit").Dict<{
-        model?: string | null | undefined;
-        reasoningEffort?: string | null | undefined;
-        updatedAt?: number | null | undefined;
-    } & import("@deepseek-ai/cosmokit").Dict, string>, import("@deepseek-ai/cosmokit").Dict<Schemastery.ObjectT<{
-        model: z<string, string>;
-        reasoningEffort: z<string, string>;
-        updatedAt: z<number, number>;
-    }>, string>>;
-}>>;
+/** The shape `ssh-tui-routes` takes in `$DSH_HOME/settings.yaml`. */
+export interface RouteMemorySettings {
+    providers: Record<string, {
+        model: string;
+        reasoningEffort: string;
+        updatedAt: number;
+    }>;
+}
+/**
+ * Settings schema for `$DSH_HOME/settings.yaml` under ssh-tui-routes.
+ *
+ * The type argument is spelled out rather than inferred: `schemastery`'s
+ * builder names its own package internally, so an inferred schema makes `tsc`
+ * emit a declaration that references a path inside `node_modules` and fails
+ * with TS2742 on any layout that does not match this machine's.
+ */
+export declare const ROUTE_MEMORY_SCHEMA: z<RouteMemorySettings>;
 export interface RememberedRoute {
     model: string;
     reasoningEffort?: string;

package/lib/types/session-list.d.ts

@@ -10,10 +10,15 @@ export declare function formatFooterCwd(cwd: string): string;
 /**
  * Switch the process into a persisted session working directory. Returns the
  * directory actually used; missing/invalid paths stay put and are reported.
+ *
+ * The target must be an absolute directory. A regular file that happens to
+ * exist at the recorded path used to pass `existsSync` and then fail inside
+ * `chdir` with a platform errno; resume now refuses it before moving.
  */
 export declare function enterSessionCwd(cwd: string | undefined, options?: {
     current?: string;
     exists?: (path: string) => boolean;
+    isDirectory?: (path: string) => boolean;
     chdir?: (path: string) => void;
 }): {
     cwd: string;

package/lib/types/session-lock.d.ts

@@ -21,6 +21,15 @@ export declare class SessionLockHeldError extends Error {
     constructor(lock: SessionLockInfo, path: string);
 }
 export declare function sessionLockPath(sessionId: string, dshHome?: string): string;
+/**
+ * Pre-digest lock path (`tui-locks/<safeId>.json`).
+ *
+ * 0.7.1 Hosts still write here. Lookup must find that file; a new Host must
+ * not bind a second lock beside a live one just because the filename changed.
+ */
+export declare function legacySessionLockPath(sessionId: string, dshHome?: string): string;
+/** Digested lock first, then the 0.7.1 name when it is different. */
+export declare function sessionLockLookupPaths(sessionId: string, dshHome?: string): string[];
 export declare function parseSessionLock(raw: string): SessionLockInfo | undefined;
 /** True when `pid` still exists on this machine (best-effort). */
 export declare function processIsAlive(pid: number): boolean;

package/lib/types/session-route.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Per-session provider/model memory.
+ *
+ * The parent route and the subagent route used to be one global choice: `/model`
+ * and `/submodel` wrote a default that every later session inherited. Once a
+ * child could run on a *different* supplier that stopped being enough — resuming
+ * an old conversation silently re-ran it on whatever the last conversation used,
+ * and there was no way to see which supplier had paid for the earlier one.
+ *
+ * Each session's effective route is recorded here, next to the TUI's other
+ * per-session state under `$DSH_HOME`, and applied when that session starts
+ * again. A new session still starts from the global default; the record only
+ * ever overrides it for the session it belongs to, and never for another one.
+ *
+ * The record is a cache of a decision, not a source of truth: every field is
+ * parsed defensively, and a route whose provider no longer exists is still
+ * applied (the launcher reports the failure the same way it would for a CLI
+ * flag).
+ *
+ * @module dsh-ssh-tui/session-route
+ */
+import { type SubagentSelectionRef } from './subagent-model.js';
+/** Subagent route as this session ran it; no provider means "follows parent". */
+export interface SessionSubagentRoute {
+    provider?: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** One session's route: what `/model`, `/provider`, `/submodel` settled on. */
+export interface SessionRoute {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+    subagent?: SessionSubagentRoute;
+    /** Epoch ms of the last write; the oldest records are pruned first. */
+    updatedAt: number;
+}
+/**
+ * How many sessions keep a record. The file is a convenience cache, and a
+ * hundred-odd conversations is more history than a resume picker offers.
+ */
+export declare const SESSION_ROUTE_LIMIT = 200;
+export declare function sessionRoutePath(dshHome?: string): string;
+/** Parse one record; anything that cannot name a route is dropped. */
+export declare function parseSessionRoute(raw: unknown): SessionRoute | undefined;
+/** Parse the whole file; a file from another version reads as empty. */
+export declare function parseSessionRoutes(raw: unknown): Map<string, SessionRoute>;
+export declare function loadSessionRoutes(path?: string): Promise<Map<string, SessionRoute>>;
+/** The record for one session, or undefined when it never had one. */
+export declare function loadSessionRoute(sessionId: string, path?: string): Promise<SessionRoute | undefined>;
+/** Keep the newest `limit` records, so the file cannot grow without bound. */
+export declare function pruneSessionRoutes(entries: ReadonlyMap<string, SessionRoute>, limit?: number): Map<string, SessionRoute>;
+export declare function saveSessionRoutes(path: string, entries: ReadonlyMap<string, SessionRoute>): Promise<boolean>;
+/**
+ * Record one session's route, leaving every other session alone.
+ *
+ * Read-modify-write on purpose: two Hosts (two SSH windows) can be open at
+ * once, and neither may drop the other's entry.
+ */
+export declare function saveSessionRoute(sessionId: string, route: Omit<SessionRoute, 'updatedAt'>, path?: string): Promise<boolean>;
+/** Whether two records describe the same route (the timestamp is ignored). */
+export declare function sameSessionRoute(left: SessionRoute | undefined, right: Omit<SessionRoute, 'updatedAt'> | undefined): boolean;
+/**
+ * Shape a live parent route plus the subagent selection into a record.
+ *
+ * Shared by the TUI (which reports what its refs hold) and the launcher (which
+ * writes it), so the two cannot disagree about what a session was running on.
+ * An empty provider or model yields nothing: a record that cannot name a route
+ * would come back as a lie.
+ */
+export declare function sessionRouteInput(input: {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+    subagent?: {
+        provider?: string;
+        model: string;
+        reasoningEffort?: string;
+    };
+}): Omit<SessionRoute, 'updatedAt'> | undefined;
+/**
+ * Providers the harness ships with. They are routable in any install even when
+ * the adapter list is still warming up, so a record naming one is never treated
+ * as stale on that basis alone.
+ */
+export declare const BUILTIN_ROUTABLE_PROVIDERS: readonly ["deepseek-official", "xai", "opencode-go", "opencode"];
+/**
+ * Whether this install can still route to a provider.
+ *
+ * Deliberately permissive: the cost of wrongly *keeping* a record is an error the
+ * harness already reports clearly (an unknown route, the same one a launch flag
+ * would hit), while wrongly *dropping* one silently loses the session's route —
+ * which is the whole feature. So a provider counts as routable when it is a
+ * built-in, appears in the adapter list, has a configured `llm-pi-ai` profile, or
+ * is listed by the adapter's own model catalog.
+ */
+export declare function providerIsRoutable(input: {
+    provider: string;
+    /** Ids from `llm.listProviders()`. */
+    listed?: readonly string[];
+    /** Ids with an `llm-pi-ai.providers.<id>` section. */
+    configured?: readonly string[];
+}): boolean;
+/** What a resumed session's record is worth in this install. */
+export interface RouteAvailabilityPlan {
+    /** The parent route, when the provider it names can still be routed to. */
+    route?: SessionRoute;
+    /** The subagent route, when its own pin can be routed to as well. */
+    subagent?: SessionSubagentRoute;
+    /** Recorded parent provider that is gone; the caller says so on screen. */
+    droppedProvider?: string;
+    /** Recorded subagent pin that is gone; the app-level setting takes over. */
+    droppedSubagentProvider?: string;
+}
+/**
+ * Decide what of a recorded route still applies.
+ *
+ * A provider that no longer exists takes its whole record with it: the session
+ * was configured around that supplier (its model, its effort, and the children
+ * it pinned), so the honest answer is the app-level default for all of it rather
+ * than a half-restored route. A pinned *child* provider that is gone is narrower:
+ * the parent route is kept and the children fall back to the app-level subagent
+ * setting. An inherited child route has no pin to check — it follows the parent,
+ * which was just found routable.
+ */
+export declare function routeAvailabilityPlan(input: {
+    recorded?: SessionRoute;
+    routable: (provider: string) => boolean;
+}): RouteAvailabilityPlan;
+/**
+ * Apply a resumed session's record to the live selection.
+ *
+ * Returns what the record was worth (see `routeAvailabilityPlan`) so the
+ * launcher can say which route the session came back on — and, when a supplier
+ * has been removed since, which one it fell back from. A new session is left
+ * alone, and so is a resumed one that never had a record: both start from the
+ * app-level defaults, which is the behaviour before any of this existed.
+ *
+ * The subagent route is applied in memory only: it belongs to the conversation
+ * being resumed, and writing it back to the settings would make one session's
+ * pin the default for every later session.
+ */
+export declare function restoreSessionRoute(input: {
+    sessionId: string;
+    resume: boolean;
+    subagentSelection: SubagentSelectionRef;
+    path?: string;
+    /** Availability test; omitted means "everything is routable". */
+    routable?: (provider: string) => boolean;
+}): Promise<RouteAvailabilityPlan>;
+/** One remembered route as the launch waterfall sees it. */
+export interface LaunchRouteSource {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+export interface LaunchRouteInput {
+    /** In-process change from `/model` or `/setup` earlier in this process. */
+    live?: LaunchRouteSource;
+    /** Launch flags (`--provider` / `--model`). */
+    cli?: {
+        provider?: string;
+        model?: string;
+    };
+    /** This session's own record, when the launch resumes it. */
+    session?: SessionRoute;
+    /** Global default (the settings file, or `agent-default-model`). */
+    saved?: LaunchRouteSource;
+    /** Last model per provider, used only when no user default section exists. */
+    remembered?: LaunchRouteSource;
+}
+export interface LaunchRoute {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/**
+ * The route a launch should run on, in one place.
+ *
+ * Precedence: an in-process change, then launch flags, then the session's own
+ * record, then the global default, then the last remembered route. A resumed
+ * conversation therefore comes back on the supplier it was actually using, while
+ * a new one still starts from the default — and an explicit flag still wins,
+ * because that is this launch's ask.
+ *
+ * The reasoning effort travels with the route it was chosen for: it is taken
+ * from whichever source supplied the provider/model, and only when the flags did
+ * not move the route away from it. A CLI that changes either half must not
+ * inherit the saved effort of a different model.
+ */
+export declare function resolveLaunchRoute(input: LaunchRouteInput): LaunchRoute;

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

@@ -24,6 +24,33 @@ export declare const DEFAULT_XAI_SUBAGENT_MODEL = "grok-4.5";
  * with flash-like ids ranked first.
  */
 export declare function defaultSubagentModelForProvider(provider: string, listed?: readonly string[], parentModel?: string): string;
+/**
+ * Canonical id of the supplier behind a route.
+ *
+ * The settings file can name the same supplier two ways — `xai` against
+ * `grok`, `deepseek-official` against `deepseek` — and a `/submodel` pin that
+ * spells the parent's own provider differently is still the parent's provider.
+ * Only those aliases collapse: an id the TUI cannot vouch for (`deepseek-eu`,
+ * `grok-mirror`, a relay) stays itself, because two routes it cannot prove
+ * share a bill are two providers.
+ */
+export declare function canonicalProviderId(provider: string | undefined): string;
+/**
+ * True when `child` is a different supplier from `parent`.
+ *
+ * This is the one condition that earns a subagent an accent colour: a child
+ * that follows the parent — or that was pinned back onto the parent's own
+ * provider — is on the parent's route and must read as such.
+ */
+export declare function subagentProviderDiffers(parent: string | undefined, child: string | undefined): boolean;
+/**
+ * Identity SGR for a subagent chip title. Same provider as the parent stays
+ * the violet used since the courtesy-name work; a different provider uses
+ * cyan so the foreign route is visible without a second color layer.
+ */
+export declare const SUBAGENT_IDENTITY_SGR = "38;5;141";
+export declare const SUBAGENT_FOREIGN_SGR = "38;5;80";
+export declare function subagentIdentitySgr(foreign: boolean): typeof SUBAGENT_IDENTITY_SGR | typeof SUBAGENT_FOREIGN_SGR;
 /**
  * True when the stored subagent model still belongs to the parent provider
  * family. An explicit leftover DeepSeek flash id after switching to xAI is
@@ -75,16 +102,42 @@ export interface SubagentSelection {
 /** Mutable selection handle shared by the settings watcher and the TUI. */
 export interface SubagentSelectionRef {
     current: SubagentSelection;
+    /**
+     * Where `current` came from.
+     *
+     * A route restored from a session's own record (`session`) outranks the
+     * settings watcher: the host fires `onChange` on writes to *any* section, so a
+     * `/model` or a `/doctor --fix` would otherwise put the app-level default back
+     * and silently drop the pin the conversation was resumed with. A user change
+     * through `/submodel` hands ownership back to the settings.
+     */
+    source?: 'settings' | 'session';
 }
-/** Settings schema for `$DSH_HOME/settings.yaml`. */
+/**
+ * Adopt a session's own subagent route, outranking the settings watcher.
+ * @param ref - the shared selection handle.
+ * @param selection - the route the session's record names.
+ */
+export declare function adoptSessionSubagentSelection(ref: SubagentSelectionRef, selection: SubagentSelection): void;
+/**
+ * Hand the ref back to the settings watcher.
+ *
+ * Called when a user change makes the settings the source again, and before a
+ * new session starts in this process — a session-scoped route must not leak into
+ * the next conversation. Only a readable section may replace the current value:
+ * resetting on a settings service that is not up yet would swap the route for
+ * the built-in default instead.
+ */
+export declare function releaseSessionSubagentSelection(ref: SubagentSelectionRef, settingsValue: unknown): void;
+/** 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/term-text.d.ts

@@ -4,6 +4,7 @@
  * Isolated so the launch session picker can clip labels without loading
  * the interactive TUI class.
  */
+import { type ColorDepth } from './color-depth.js';
 /**
  * Codex-style compact elapsed: `0s`, `1m 05s`, `1h 01m 01s`.
  * Used by the workspace wait card while the model has not streamed yet.
@@ -116,9 +117,9 @@ export declare function wrapTracked(text: string, width: number): {
     end: number;
 }[];
 /** Paint one already-wrapped output line by the segments overlapping its range. */
-export declare function paintSegmentedLine(line: string, start: number, end: number, segments: readonly TextSegment[]): string;
+export declare function paintSegmentedLine(line: string, start: number, end: number, segments: readonly TextSegment[], depth?: ColorDepth): string;
 /** Wrap `text` and color each output line by overlapping `segments`. */
-export declare function wrapSegmented(text: string, width: number, segments: readonly TextSegment[]): string[];
+export declare function wrapSegmented(text: string, width: number, segments: readonly TextSegment[], depth?: ColorDepth): string[];
 export declare function truncate(text: string, maxLines: number): string;
 /** One OSC-8 hyperlink span in a painted row, in display columns. */
 export interface PaintedLinkHit {

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 {};