dsh-ssh-tui 0.7.2 → 0.7.4

package/lib/types/attach.d.ts

@@ -48,6 +48,12 @@ export interface LiveHost {
     kind: 'attachable' | 'zombie';
     sock: string;
     pid: number;
+    /**
+     * The lock's own view of the session: `attached` while a display relay is
+     * connected, `paused` / `running-detached` once its window is gone. Absent on
+     * a lock written before the field existed, which must not read as "in use".
+     */
+    state?: string;
     exitWatch?: {
         dispose(): void;
         exited: Promise<number | null>;
@@ -97,6 +103,8 @@ export interface AttacherDeps {
         replaced(sessionId: string): string;
         flapping(sessionId: string): string;
         zombie(sessionId: string, pid: number): string;
+        /** Refused: a window is on this session right now (see `attachOrSpawn`). */
+        attached(sessionId: string, pid: number): string;
     };
     locksDisabled?(): boolean;
     now?(): number;

package/lib/types/commands.d.ts

@@ -39,6 +39,9 @@ export declare const LOCAL_COMMANDS: readonly [{
 }, {
     readonly name: "disconnect";
     readonly key: "cmd.disconnect";
+}, {
+    readonly name: "notify";
+    readonly key: "cmd.notify";
 }, {
     readonly name: "approval";
     readonly key: "cmd.approval";

package/lib/types/diag.d.ts

@@ -21,6 +21,26 @@ export interface DiagSnapshot {
     hostVersion: string;
     nodeVersion: string;
     platform: string;
+    /**
+     * Which terminal we classified, and the capabilities we then claimed. A
+     * Windows report that says "the mouse does nothing" or "copy did nothing" is
+     * otherwise guesswork: conhost and Windows Terminal look identical from the
+     * transcript, and the claimed flags are what the TUI actually acted on.
+     */
+    terminal?: {
+        family: string;
+        label: string;
+        mouse: boolean;
+        bracketedPaste: boolean;
+        alternateScreen: boolean;
+        osc52: boolean;
+        osc8: boolean;
+        title: boolean;
+        /** `DSH_TUI_TERM_CAPS` tokens that were rejected (typos), for the row. */
+        ignoredOverrides: readonly string[];
+        /** Chrome is being drawn in ASCII because the console cannot decode UTF-8. */
+        ascii: boolean;
+    };
     /**
      * What the palette resolved to and which hints decided it. A "no colour on
      * Windows" report is otherwise guesswork: `TERM` is unset there by default.
@@ -72,7 +92,6 @@ export declare function readErrTail(sessionId: string, dshHome?: string): Promis
  * The first entry is the actionable one; the rest is supporting context.
  */
 export declare function diagVerdicts(snapshot: DiagSnapshot): string[];
-/** The whole report as transcript lines. Pure. */
 export declare function formatDiag(snapshot: DiagSnapshot): string[];
 /** Gather everything the report needs. Every probe is best-effort. */
 export declare function collectDiag(options: {

package/lib/types/dialogs.d.ts

@@ -55,6 +55,22 @@ export interface InspectDialog {
     subagentSessionId?: string;
     /** `/find` already scrolled to its hit here; later repaints keep the offset. */
     searchRevealed?: boolean;
+    /**
+     * What the copy key takes while this overlay is up.
+     *
+     * The reader asked to see this body full-screen, so the body is what they
+     * mean by "copy this" — the overlay has no input line, and `/copy` typed at
+     * the prompt is covered by it. Undefined falls back to whatever is selected
+     * behind the overlay, which is the card the reader opened to get here.
+     */
+    copyText?: string;
+    /**
+     * Confirmation line shown in place of the key hint after an in-overlay copy.
+     *
+     * The notice row the copy also pushes is behind this screen, and silence after
+     * a clipboard write is the one thing that reads as a failure.
+     */
+    notice?: string;
 }
 export type Dialog = ConfirmDialog | QuestionDialog | OnboardingDialog | InspectDialog;
 export interface DialogAnswer {

package/lib/types/display-sock.d.ts

@@ -5,6 +5,29 @@ export declare const FRAME_HELLO = 4;
 export declare const FRAME_GOODBYE = 5;
 export declare const FRAME_RTT = 6;
 export declare const FRAME_REPLACED = 7;
+/** Host → relay: round-trip your terminal now and say what it answered. */
+export declare const FRAME_PROBE = 8;
+/** Relay → Host: the answer to {@link FRAME_PROBE}. */
+export declare const FRAME_PROBE_REPLY = 9;
+/** A prober → Host: is a window *really* on this session? Does not claim it. */
+export declare const FRAME_QUERY = 10;
+/** Host → prober: the answer to {@link FRAME_QUERY}. */
+export declare const FRAME_QUERY_REPLY = 11;
+/**
+ * What a relay's own terminal round trip said.
+ *
+ * `live` — the terminal answered just now, so somebody has a screen in front of
+ *   them. `silent` — it answered when this relay attached and does not answer
+ *   now: that window is gone. The distinction is the whole point: a cut SSH link
+ *   leaves the launcher *connected* (it sees no hangup until sshd does, which
+ *   can be hours with TCP keepalive), so the socket alone cannot tell a live
+ *   window from a dead one — only the far end can. `unknown` — it never answered
+ *   (a pipe, a dumb terminal, or a link that was already dead at attach), and
+ *   silence must not be read as an answer.
+ */
+export type TerminalVerdict = 'live' | 'silent' | 'unknown';
+/** What a Host tells a prober about the window on its session. */
+export type AttachmentVerdict = 'attached' | 'detached' | 'unknown';
 /**
  * Drop launcher SIGTERM/SIGINT/SIGHUP so closing SSH cannot dispose the tree
  * before hangup handling. Leaving the session with setsid() is best-effort:
@@ -71,6 +94,14 @@ export declare function sessionSockLookupPaths(sessionId: string, dshHome?: stri
  * device names (`CON`, `NUL`, …) from becoming the file stem.
  */
 export declare function sessionErrPath(sessionId: string, dshHome?: string, platform?: NodeJS.Platform): string;
+/**
+ * Where the hidden-console bootstrap writes the Host's pid.
+ *
+ * On `\\.\pipe\` Windows there is no socket file to derive a name from, and the
+ * state directory already holds the per-session lock and stderr log, so the pid
+ * file lives beside them. It is removed as soon as it has been read.
+ */
+export declare function sessionBootstrapPidPath(sessionId: string, dshHome?: string): string;
 /** Pre-digest Host stderr log next to the 0.7.1 socket, when that name differs. */
 export declare function legacySessionErrPath(sessionId: string, dshHome?: string, platform?: NodeJS.Platform): string | undefined;
 export declare function encodeFrame(type: number, payload?: Buffer): Buffer;
@@ -81,6 +112,12 @@ export declare function decodeResize(payload: Buffer): {
 } | undefined;
 export declare function encodeRtt(rttMs: number | undefined): Buffer;
 export declare function decodeRtt(payload: Buffer): number | undefined;
+export declare function encodeProbe(): Buffer;
+export declare function encodeProbeReply(verdict: TerminalVerdict): Buffer;
+export declare function decodeProbeReply(payload: Buffer): TerminalVerdict;
+export declare function encodeQuery(): Buffer;
+export declare function encodeQueryReply(verdict: AttachmentVerdict): Buffer;
+export declare function decodeQueryReply(payload: Buffer): AttachmentVerdict;
 /** Incremental decoder for one socket. */
 export declare class FrameReader {
     private buffer;
@@ -105,19 +142,45 @@ export interface DisplayHostHandlers {
 export declare class DisplayHost {
     readonly path: string;
     private readonly handlers;
-    /** Test seam: how long a silent connection may wait for its HELLO. */
+    /** Test seams: how long a silent connection may wait for its HELLO, and
+     *  how long a relay may take to report its terminal round trip. */
     private readonly options;
     private server;
     private socket;
     private reader;
     attached: boolean;
+    /** Set while a {@link FRAME_PROBE} round trip is waiting for its answer. */
+    private probeSettle;
+    private probeInFlight;
     constructor(path: string, handlers: DisplayHostHandlers, 
-    /** Test seam: how long a silent connection may wait for its HELLO. */
+    /** Test seams: how long a silent connection may wait for its HELLO, and
+     *  how long a relay may take to report its terminal round trip. */
     options?: {
         helloGraceMs?: number;
+        probeTimeoutMs?: number;
     });
     listen(): Promise<void>;
     private accept;
+    /**
+     * Whether a window is really on this session — asked of the window itself.
+     *
+     * "The socket answers" is not evidence. A relay whose SSH link was cut stays
+     * connected (its launcher sees no hangup until sshd does), and the Host then
+     * truthfully reports a display that no longer has a screen behind it. Only the
+     * far end can settle it, so this round-trips the terminal through the relay.
+     */
+    attachmentVerdict(): Promise<AttachmentVerdict>;
+    /** One answer to one prober; never claims the display, never throws. */
+    private answerQuery;
+    /**
+     * Ask the claimed relay to round-trip its terminal, with a deadline.
+     *
+     * Sharing one in-flight round trip matters: a second question while the first
+     * is unanswered would be settled by the first reply, and two windows asking at
+     * once is a normal resume, not an error.
+     */
+    private probeTerminal;
+    private settleProbe;
     sendStdout(bytes: Buffer | string): boolean;
     sendGoodbye(): void;
     close(): Promise<void>;
@@ -134,6 +197,24 @@ export declare class DisplayHost {
  * it without stealing the display.
  */
 export declare function displaySockExists(path: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * How long a prober waits for the Host's answer to {@link FRAME_QUERY}.
+ *
+ * It has to cover the relay's own two probe windows (see
+ * {@link DISPLAY_PROBE_TIMEOUT_MS}) plus the hop; the answer only takes this
+ * long when the display really is silent.
+ */
+export declare const DISPLAY_QUERY_TIMEOUT_MS = 4000;
+/**
+ * Ask a live Host whether a window is really on its session.
+ *
+ * `undefined` means the Host did not answer — an older Host that does not know
+ * the frame, or one whose event loop is stuck. Every caller must read that as
+ * "cannot tell" and never as "free": the cost of the doubt is one confirmation
+ * prompt, and the cost of guessing wrong is taking a session away from a window
+ * somebody is still typing in.
+ */
+export declare function queryDisplayAttachment(path: string, timeoutMs?: number): Promise<AttachmentVerdict | undefined>;
 /** Watches a freshly spawned Host so a crash is reported immediately. */
 export interface HostExitWatch {
     /** Resolves with the exit code (or null when killed) once the Host exits. */
@@ -141,6 +222,8 @@ export interface HostExitWatch {
     /** Stop watching; call once the channel is confirmed up. */
     dispose(): void;
 }
+/** Exported for the test that pins its loop-ref behaviour; not public API. */
+export declare function watchHostPid(pid: number): HostExitWatch;
 /**
  * How long a dead-pid report waits for the child's `exit` event before giving
  * up on its code. The event is normally delivered within a tick; the bound only
@@ -191,33 +274,64 @@ export declare function quietTerminalInput(stdin?: NodeJS.ReadStream): number;
  * written into a link that may already be dead.
  */
 export declare function restoreTerminalInput(stdin?: NodeJS.ReadStream): void;
+/** Test seam for {@link spawnDetachedHost}; production passes nothing. */
+export interface SpawnHostOptions {
+    /**
+     * Start the Host through this command instead of resolving the real one, or
+     * `null` to spawn it directly even where a bootstrap exists.
+     *
+     * `null` is for the tests that are about the *direct* path — the fixture Hosts
+     * in `tests/display-host-e2e.test.mjs` assert on the child's exit code, which
+     * only a real child handle can report (a pid watch resolves `null`). The
+     * bootstrap has its own coverage: the builders on every platform, and the real
+     * Windows probes end to end.
+     */
+    bootstrap?: {
+        command: string;
+        args: string[];
+    } | null | undefined;
+    /** How long the bootstrap may take to report a pid (Windows PowerShell start). */
+    bootstrapTimeoutMs?: number;
+}
 /**
- * How to start the background Host so it outlives this process *and* does not
- * make its own children flash console windows on Windows.
+ * Start the Host through the hidden-console bootstrap and return its pid, or
+ * `undefined` when the bootstrap could not report one.
  *
- * POSIX wants `detached: true` (setsid) so the Host survives the launcher and a
- * hung-up terminal.
+ * `spawnSync` on purpose. The pid has to be in hand before this function
+ * returns (the caller watches it, and the fallback must never leave two Hosts
+ * for one session), and the cost is one bounded wait while the boot splash is
+ * already on screen. PowerShell exits as soon as `Start-Process` has created the
+ * Host, so the wait is its own start-up, not the Host's.
  *
- * 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.
+ * Falling back is safe exactly when nothing was printed: `Start-Process -PassThru`
+ * either starts the Host and prints its id, or throws before starting anything
+ * (`$ErrorActionPreference = 'Stop'`). A *timeout* is the one case where a Host
+ * might exist and the pid was lost, so it does not fall back — it reports.
+ */
+export declare function spawnHostThroughBootstrap(bootstrap: {
+    command: string;
+    args: string[];
+}, options: {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    timeoutMs: number;
+    /** File the bootstrap writes the Host's pid to. */
+    pidFile: string;
+}): {
+    pid: number;
+} | undefined;
+/**
+ * Spawn a detached Host copy of this `dsh` invocation and return its sock path.
  *
- * Pure and platform-parameterised so the Windows branch can be asserted from
- * Linux (see docs/platform.md).
+ * On Windows the Host goes through {@link hostBootstrapCommand} when the OS
+ * PowerShell is available: a direct spawn there cannot both survive the
+ * launcher (libuv's `KILL_ON_JOB_CLOSE` job takes a non-detached child with it)
+ * and avoid flashing console windows (`detached` is DETACHED_PROCESS, which makes
+ * Windows ignore `CREATE_NO_WINDOW`). The bootstrap gives the Host a console of
+ * its own, hidden — see `docs/platform.md`. Without it, the direct spawn below
+ * is still what runs, with the old semantics.
  */
-export declare function hostSpawnOptions(platform?: NodeJS.Platform): {
-    detached: boolean;
-    windowsHide: boolean;
-};
-/** Spawn a detached Host copy of this `dsh` invocation and return its sock path. */
-export declare function spawnDetachedHost(sessionId: string, platform?: NodeJS.Platform): SpawnedHost;
+export declare function spawnDetachedHost(sessionId: string, platform?: NodeJS.Platform, options?: SpawnHostOptions): SpawnedHost;
 export declare function probeDisplaySock(path: string, timeoutMs?: number): Promise<boolean>;
 export interface RelayResult {
     /** Host sent goodbye — user exited from the attached session. */
@@ -230,6 +344,9 @@ export interface DisplayRelayOptions {
     signals?: Pick<NodeJS.Process, 'on' | 'off' | 'removeListener'>;
     /** Link kind for the RTT probe; defaults to this process's SSH env. */
     ssh?: boolean;
+    /** Re-measure cadences (tests); defaults to {@link RTT_RECHECK_FIRST_MS} / {@link RTT_RECHECK_MS}. */
+    rttFirstRecheckMs?: number;
+    rttRecheckMs?: number;
     /** Typing captured before this relay existed; sent to the Host after HELLO. */
     seed?: string;
     /**

package/lib/types/doctor.d.ts

@@ -14,7 +14,7 @@
  * `collectDoctor` and every probe is best-effort. Nothing leaves the machine.
  * @module dsh-ssh-tui/doctor
  */
-import { type PatchAnalysis, type PatchRowRef, type RosterRow } from './preset-rows.js';
+import { type HostGeneration, type PatchAnalysis, type PatchRowRef, type RosterRow } from './preset-rows.js';
 export type DoctorStatus = 'ok' | 'warn' | 'fail';
 export interface DoctorCheck {
     id: string;
@@ -64,6 +64,12 @@ export interface DoctorFacts {
         range?: string;
         releases: Record<string, string>;
     };
+    /**
+     * Which settings protocol the host speaks; decides which rows a terminal
+     * profile has to mount itself. Absent means the 0.1.5 line, so a snapshot
+     * built before this field existed keeps its verdicts.
+     */
+    generation?: HostGeneration;
     /** Distinct installs of `@deepseek-ai/dsh-scope` found from the anchors. */
     scopeCopies: readonly string[];
     /** Absent when routing could not be read (no settings service). */
@@ -101,6 +107,7 @@ export declare function collectDoctor(options: {
     services: DoctorFacts['services'];
     anchors: ReadonlyArray<string | undefined>;
     routing?: DoctorRouting;
+    generation?: HostGeneration;
 }): Promise<DoctorFacts>;
 /** Rows `/doctor --fix` would mount, given the services the composition registered. */
 export declare function rowsToRepair(facts: DoctorFacts): RosterRow[];

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

@@ -1,35 +1,168 @@
 /**
- * Dual-stack shims for dsh 0.1.2-rc.1 and 0.1.5-rc.1 (and the 0.1.5-alpha
- * handle API that landed with it).
+ * Dual-stack shims for the dsh 0.1.5-rc and 0.1.7-rc lines (including the
+ * 0.1.5-alpha handle API that landed with the former).
  *
- * 0.1.2 turned settings free functions into `SettingsProvider` methods and
- * replaced `Session.events` with on-demand readers. 0.1.5 replaced
- * `SessionPersistence.list`/`inspect`/`locate` with snapshot `list` plus
- * per-session `open` handles, and moved live tokens from durable
- * `assistant/chunk` events to process-local `agent/assistant-stream`.
- * Every shim here picks the API that is actually present so one build
- * runs on either host.
+ * 0.1.5 resolves settings through `SettingsProvider.get`/`installSection` and
+ * exposes session persistence as snapshot `list` plus per-session `open`
+ * handles; live tokens arrive on the process-local `agent/assistant-stream`.
+ * 0.1.7 replaced the settings service with schema-projected forms. Every shim
+ * here picks the API that is actually present so one build runs on either
+ * host line.
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
 import type { SessionEvent } from '@deepseek-ai/dsh-session';
-import type { SettingsNamespace, SettingsSectionHooks } from '@deepseek-ai/dsh-settings';
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import type z from '@deepseek-ai/schemastery';
 /**
- * 0.1.1-rc.2 wraps namespaces via `settingsNamespace()`; 0.1.2+ brands them at
- * the type level and takes the plain string at runtime. A cast covers both.
+ * The source kind this plugin declares for the messages it commits itself: the
+ * plan-close nudge and the approval-denied steering notice.
+ *
+ * These used to ride the released catch-all wrapper —
+ * `<kind: 'plugin', plugin: 'dsh-ssh-tui'>` — which 0.1.5 shipped as a member and
+ * 0.1.7 deleted ("each producer declares its own `kind` in its own module; there
+ * is no shared catch-all `plugin` kind"). Worse than missing on 0.1.7: its V4
+ * native admission *refuses* the wrapper outright, so an append under that
+ * spelling throws "format v4 message requires a producer-owned source kind" and
+ * takes the whole turn down with it — which is what the plan nudge and the
+ * approval-denied notice did to any turn they fired in on a V4 session.
+ *
+ * The producer-owned spelling is the one shape both supported lines admit: the
+ * wrapper was only ever mandatory for `system/message` (`SystemMessage['source']`
+ * is the `plugin` member on 0.1.5), while user-role messages have always carried
+ * a producer's own kind — the 0.1.5 line's own `goal`, `webhook`, and
+ * `agent-instructions` producers all commit `kind: '<their name>'`.
+ */
+export declare const TUI_SOURCE_KIND = "dsh-ssh-tui";
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'dsh-ssh-tui': {
+            kind: 'dsh-ssh-tui';
+        } & ContextFormed;
+    }
+}
+/**
+ * The kind the V3-to-V4 lane gives the same messages in a converted log.
+ *
+ * The conversion lifts a released plugin wrapper to the producer's kind when it
+ * knows the plugin, and falls back to `plugin:<name>` when it does not — which is
+ * this plugin's case, so a resumed V3 session carries the prefixed spelling.
+ */
+export declare const TUI_CONVERTED_SOURCE_KIND = "plugin:dsh-ssh-tui";
+/**
+ * Whether a durable message source came from this plugin.
+ *
+ * Three spellings reach a reader: the producer-owned kind written now, the
+ * `plugin:`-prefixed compatibility kind the V3-to-V4 conversion assigns, and the
+ * original wrapper (`kind: 'plugin'` + `plugin: 'dsh-ssh-tui'`) that a log
+ * committed before this change — or an unconverted V3 file read on the 0.1.5
+ * line — still carries.
+ *
+ * @param kind - the source's `kind`, when it has one.
+ * @param plugin - the source's legacy `plugin` field, when it carries the wrapper.
+ * @returns whether this plugin produced the message.
+ */
+export declare function isTuiMessageSource(kind: unknown, plugin?: unknown): boolean;
+/**
+ * Settings namespaces are branded strings at the type level on both supported
+ * lines; this cast supplies the brand from a plain literal.
  */
 export declare function settingsNamespace(value: string): SettingsNamespace;
 /**
- * Register a settings section: 0.1.2-rc.1 moved the free function onto the
- * `settings` service as `installSection`, callable only once that service is
- * injected (plugins apply before it, so `ctx.inject` must defer — same
- * pattern the harness's own packages use); 0.1.1-rc.2 keeps the free
- * function, which defers internally and is safe at apply time.
+ * Hooks a settings consumer hands to {@link installSettingsSection}.
+ *
+ * Spelled out locally instead of imported: 0.1.7 deleted the
+ * `SettingsSectionHooks` export, and this shape is the whole contract the three
+ * call sites use.
+ */
+export interface SettingsSectionHooks<T> {
+    /**
+     * Receive the active configuration source: the resolved settings value while
+     * a section is attached. Called at attach and again after every change.
+     * @param current - thunk returning the currently authoritative value.
+     */
+    setSource(current: () => T): void;
+    /**
+     * Re-judge anything derived from the source — registration-level facts,
+     * memoized resolutions — after an attach or a committed change.
+     */
+    onChange(): void;
+    /** Reject a resolved section this consumer could not act on. */
+    validate?(value: T): void;
+}
+/** Which settings protocol the running host speaks. */
+export type SettingsGeneration = 'legacy' | 'forms';
+/**
+ * The host's settings generation, as feature detection rather than a version.
+ *
+ * `legacy` (0.1.5) resolves a namespace through `settings.get`; `forms` (0.1.7)
+ * has no `get` and projects a form per loader entry. Callers that differ by
+ * generation — which profile rows a terminal profile must mount, for one — read
+ * it here instead of sniffing package versions.
+ *
+ * Before the service exists (a plugin applies before it is mounted) the same
+ * split shows up as the roster package's absence, and the answer is memoized as
+ * soon as the service is seen so a later call cannot disagree with an earlier
+ * one.
+ */
+export declare function hostSettingsGeneration(ctx: Context): SettingsGeneration;
+/** Forget the memoized descriptors so the next read re-walks the forms. */
+export declare function invalidateSettingsCache(ctx: Context): void;
+/**
+ * Read one settings section.
+ *
+ * 0.1.5 resolves it through `get(ns)`. 0.1.7 has no `get`, so the value comes
+ * from the entry's descriptor, which projects the live config — volatile fields
+ * only, i.e. exactly the fields its form exposes — and returns `undefined` when
+ * no entry carries that id.
+ */
+export declare function readSettingsSection(ctx: Context, ns: SettingsNamespace): unknown;
+/**
+ * The user's own settings document, keyed by namespace, on either line.
+ *
+ * 0.1.5 publishes it as `settings.document`. 0.1.7 dropped the property — the
+ * document is the profile patch now — but each descriptor still carries the
+ * user layer it was built from, so the same view is reconstructible. Callers
+ * that ask "did the user configure this?" must use this, not
+ * {@link readSettingsSection}: a resolved read also carries the composition
+ * base and schema defaults, which is exactly what such a caller must not
+ * mistake for a user choice.
+ */
+export declare function settingsDocument(ctx: Context): Record<string, unknown> | undefined;
+/**
+ * Mark one schema field as form-writable on the 0.1.7 line.
+ *
+ * 0.1.7 projects only fields whose schema node carries the `volatile` meta, and
+ * refuses a settings write to any other path. The 0.1.5 schemastery (3.18.2)
+ * has no such builder, so the call is feature-detected rather than typed: on
+ * that line the marker means nothing and the schema is returned untouched.
+ */
+export declare function liveField<T>(schema: z<T>): z<T>;
+/**
+ * Register a settings section.
+ *
+ * 0.1.5 publishes the `settings` service with `installSection`, callable only
+ * once that service is injected (plugins apply before it, so `ctx.inject` must
+ * defer — same pattern the harness's own packages use).
+ *
+ * 0.1.7 removed it. The section is now the loader entry's own `Config`
+ * schema — this plugin's is `ssh-tui`, and the two auxiliary namespaces are
+ * carried by the `dsh-ssh-tui/settings-*` rows in `cordis.patch.yml` — so the
+ * only thing left for a consumer to wire is the live read (`setSource`) and the
+ * change notification (`onChange`).
  */
 export declare function installSettingsSection<T>(ctx: Context, ns: SettingsNamespace, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>): void;
 /**
- * Read the full durable event log: 0.1.2-rc.1 replaced the `Session.events`
- * property with on-demand readers; 0.1.1-rc.2 still exposes the property.
+ * Whether a tool result reports failure.
+ *
+ * 0.1.5 carries `isError` on the `tool-result` content block; 0.1.7 removed
+ * that block from `ContentBlockMap` and moved the flag onto the message
+ * itself. Both are read, so one build understands either host.
+ */
+export declare function toolResultFailed(message: unknown): boolean;
+/**
+ * Read the full durable event log. Both supported lines read it on demand
+ * through `snapshotEvents()`.
  */
 export declare function sessionEvents(session: object): readonly SessionEvent[];
 /**
@@ -60,7 +193,6 @@ export interface SessionHeaderLike {
 /** Logical log plus the header it belongs to. */
 export interface SessionInspectionLike {
     events: readonly unknown[];
-    meta?: SessionHeaderLike;
     header?: SessionHeaderLike;
     /**
      * Backend state for the slice. `detached` means the backend never
@@ -71,27 +203,28 @@ export interface SessionInspectionLike {
     eventState?: string;
 }
 /**
- * 0.1.2 `list()` returns headers; 0.1.5 returns `{ header, revision, … }`
- * snapshots. Normalize to headers so the picker does not care which host
+ * Both supported lines return `{ header, revision, … }` snapshots from
+ * `list()`; normalize to the header so the picker does not care which host
  * it is talking to.
  */
 export declare function listPersistenceHeaders(persistence: object): Promise<SessionHeaderLike[]>;
 /**
- * 0.1.2 `inspect(id)` returns `{ meta, events }`. 0.1.5 dropped inspect in
- * favour of `open(id, 'read')` + `handle.read()`. Close the handle so a
- * listing pass does not pin write ownership.
+ * Read one session through `open(id, 'read')` + `handle.read()`, the access
+ * both supported lines expose. Close the handle so a listing pass does not pin
+ * write ownership.
  */
 export declare function inspectPersistenceSession(persistence: object, id: unknown): Promise<SessionInspectionLike>;
-/** 0.1.2 owns `locate(header)`; 0.1.5 hid it on the JSONL backend. */
+/**
+ * A session's artifact path from its header. Both supported lines still
+ * implement `locate()` on the JSONL backend, but their typings keep it
+ * private, so the call stays feature-detected.
+ */
 export declare function persistenceLocate(persistence: object, meta: object): {
     path?: string;
 } | undefined;
-/**
- * 0.1.2 command input advertised `images`; 0.1.5 renamed the flag to
- * `attachments`. Either true means the slash command accepts composer files.
- */
+/** Whether a command's input admits the composer's attachments. */
 export declare function commandAcceptsAttachments(input: unknown): boolean;
-/** One model stream chunk, from either `assistant/chunk` or `agent/assistant-stream`. */
+/** One chunk from a live `agent/assistant-stream` frame. */
 export interface StreamChunkLike {
     type: string;
     text?: string;
@@ -133,12 +266,12 @@ export declare function streamFrameAttemptId(frame: unknown): unknown;
  */
 export declare function streamFirstTokenTime(stream: unknown): number | undefined;
 /**
- * Durable `assistant/chunk` payload, or a live stream frame's inner chunk.
+ * A live `agent/assistant-stream` chunk frame's inner chunk plus its framing.
  *
- * `fallback` supplies the turn/step for live chunk frames, which do not carry
- * them (see {@link streamFrameOwner}).
+ * `fallback` supplies the turn/step, which chunk frames do not carry (see
+ * {@link streamFrameOwner}).
  */
-export declare function streamChunkOf(eventOrFrame: unknown, fallback?: {
+export declare function streamChunkOf(frame: unknown, fallback?: {
     turn: number;
     step: number;
 }): {
@@ -147,20 +280,16 @@ export declare function streamChunkOf(eventOrFrame: unknown, fallback?: {
     step: number;
     time: number;
     /**
-     * False when neither the source nor a fallback carried a real turn/step.
+     * False when neither the frame nor a fallback carried a real turn/step.
      * Usage folded under such a chunk would be filed under a bogus key (0:0)
      * that `step/end` never clears, inflating the session totals forever.
      */
     stepKnown: boolean;
 } | undefined;
-/** Durable event type as a plain string so 0.1.5 hosts can omit `assistant/chunk`. */
-export declare function sessionEventType(event: unknown): string;
-/** True when this event is a live-or-durable assistant token that replay should skip. */
-export declare function isAssistantStreamEvent(event: unknown): boolean;
-/**
- * Subscribe to a host event that may not exist on the compile-time Events
- * map. 0.1.5 emits `agent/assistant-stream`; 0.1.2 never does. Cordis
- * still accepts the string; the listener is simply never called on 0.1.2.
+/**
+ * Subscribe to a host event whose scoped payload type does not match this
+ * build's `Events` map. Both supported lines emit `agent/assistant-stream`,
+ * and Cordis accepts the plain event name at runtime.
  */
 export declare function listenHostEvent(ctx: {
     on: (event: never, handler: never) => unknown;

package/lib/types/footer.d.ts

@@ -105,7 +105,9 @@ export declare function fitFooterChips(chips: readonly FooterChip[], width: numb
  * the preset-owned tools are missing. It leads the strip and keeps its glyph
  * longest, because it is the one group that reports a broken install.
  */
-export declare function footerHealthChip(missing: boolean, color?: boolean): FooterChip | undefined;
+export declare function footerHealthChip(missing: boolean, color?: boolean, 
+/** Which rows are missing: the 0.1.5 roster, or the 0.1.7 agent plane. */
+kind?: 'roster' | 'agent-plane'): FooterChip | undefined;
 export declare function fitFooterStatsLine(chip: string, groups: readonly string[], width: number): string;
 export type FooterActivityKind = 'plan-review' | 'waiting' | 'compacting' | 'retry' | 'subagents' | 'tools' | 'plan-open' | 'plan-pending' | 'goal' | 'waiting-llm' | 'idle';
 export interface FooterStatusInput {