@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/sessions/store.js

@@ -0,0 +1,221 @@
+/**
+ * The session index — a local cache keyed by the backend's own change token.
+ *
+ * Deriving a session's title costs a bounded read; doing it for every session
+ * on every picker open costs that read times the history. The persistence
+ * service already hands out the exact token needed to avoid it:
+ * `listSnapshots()` returns, per session, an opaque revision that changes
+ * whenever the stored log changes. An entry whose revision still matches is
+ * reused verbatim; anything else is re-derived. Steady state is therefore zero
+ * log reads, and a session edited by another client (the store is shared with
+ * dsh web) invalidates itself without any coordination.
+ *
+ * The revision is treated as opaque, as its contract requires. It happens to
+ * be stat-derived today, but parsing it to shortcut a `stat` would couple this
+ * cache to one backend's private format and break the moment a store without
+ * per-session files is used.
+ *
+ * Two halves live in one entry because they have different lifetimes:
+ * `derived` facts come from the log and die with the revision, while `branch`
+ * is a local note about how this install used the session and no log change
+ * can invalidate it. Keeping them in one record with one governing revision
+ * field makes that boundary explicit instead of implied.
+ *
+ * Every operation is best-effort. The index is a cache: a corrupt file, a
+ * losing concurrent write, or a read-only home directory costs a re-derivation
+ * and nothing else, so nothing here throws.
+ *
+ * @module dsh-cli/sessions/store
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from '../../utils/paths.js';
+/**
+ * Bumped for cached mtime. Version 3 derivations remain readable and receive
+ * that field on their next listing; version 2 could cache incomplete reads as
+ * empty, so only its branch notes survive.
+ */
+const SCHEMA_VERSION = 4;
+const INDEX_FILE = join(DATA_DIR, 'session-index.json');
+let loadedStamp;
+let loadedIndex;
+function indexStamp() {
+    try {
+        const stats = statSync(INDEX_FILE);
+        return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Cheap file generation check for asynchronous listing writes. */
+export function indexFileStamp() {
+    return indexStamp();
+}
+/** A title source as written to disk, or undefined for anything unexpected. */
+function readTitleSource(value) {
+    return value === 'renamed' || value === 'auto' || value === 'prompt' || value === 'fallback'
+        ? value
+        : undefined;
+}
+/** Narrow one persisted entry; an unrecognizable record is simply absent. */
+function readEntry(value, derivedValid) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const branch = typeof record['branch'] === 'string' ? record['branch'] : undefined;
+    const raw = derivedValid ? record['derived'] : undefined;
+    if (raw === null || typeof raw !== 'object')
+        return { derived: undefined, branch };
+    const derived = raw;
+    const revision = derived['revision'];
+    const bytes = derived['bytes'];
+    const modifiedAt = derived['modifiedAt'];
+    const identity = derived['identity'];
+    const anchor = derived['anchor'];
+    const title = derived['title'];
+    const titleSource = readTitleSource(derived['titleSource']);
+    const titleComplete = derived['titleComplete'];
+    if (typeof revision !== 'string' ||
+        typeof bytes !== 'number' ||
+        !Number.isFinite(bytes) ||
+        bytes < 0 ||
+        (modifiedAt !== undefined && (typeof modifiedAt !== 'number' || !Number.isFinite(modifiedAt))) ||
+        (identity !== undefined && typeof identity !== 'string') ||
+        (anchor !== undefined && typeof anchor !== 'string') ||
+        typeof title !== 'string' ||
+        titleSource === undefined ||
+        typeof titleComplete !== 'boolean' ||
+        typeof derived['hasPrompt'] !== 'boolean') {
+        return { derived: undefined, branch };
+    }
+    return {
+        branch,
+        derived: {
+            revision,
+            bytes,
+            modifiedAt: typeof modifiedAt === 'number' ? modifiedAt : undefined,
+            identity: typeof identity === 'string' ? identity : undefined,
+            anchor: typeof anchor === 'string' ? anchor : undefined,
+            title,
+            titleSource,
+            titleComplete,
+            hasPrompt: derived['hasPrompt'] === true,
+            model: typeof derived['model'] === 'string' ? derived['model'] : undefined,
+            label: typeof derived['label'] === 'string' ? derived['label'] : undefined,
+        },
+    };
+}
+/**
+ * Load the cache.
+ * @returns The parsed index; version 3 derivations are upgraded lazily and
+ *   version 2 retains branch notes only.
+ */
+export function readIndex() {
+    const stamp = indexStamp();
+    if (loadedIndex !== undefined && loadedStamp === stamp)
+        return new Map(loadedIndex);
+    const index = new Map();
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(INDEX_FILE, 'utf8'));
+    }
+    catch {
+        loadedStamp = stamp;
+        loadedIndex = index;
+        return new Map(index);
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        loadedStamp = stamp;
+        loadedIndex = index;
+        return new Map(index);
+    }
+    const file = parsed;
+    if (file['version'] !== SCHEMA_VERSION && file['version'] !== 3 && file['version'] !== 2) {
+        loadedStamp = stamp;
+        loadedIndex = index;
+        return new Map(index);
+    }
+    const entries = file['entries'];
+    if (entries === null || typeof entries !== 'object') {
+        loadedStamp = stamp;
+        loadedIndex = index;
+        return new Map(index);
+    }
+    for (const [id, value] of Object.entries(entries)) {
+        const entry = readEntry(value, file['version'] === SCHEMA_VERSION || file['version'] === 3);
+        if (entry !== undefined)
+            index.set(id, entry);
+    }
+    loadedStamp = stamp;
+    loadedIndex = index;
+    return new Map(index);
+}
+/**
+ * Persist the cache, atomically.
+ *
+ * The write goes to a per-process temporary name and is renamed into place, so
+ * a reader never observes a half-written file and a crash never leaves one.
+ * A concurrent writer may win the rename; the loser's derivations are simply
+ * recomputed next time.
+ *
+ * @param index - The index to store. Entries are written in insertion order.
+ */
+export function writeIndex(index) {
+    const entries = {};
+    for (const [id, entry] of index) {
+        entries[id] = {
+            ...(entry.derived === undefined ? {} : { derived: entry.derived }),
+            ...(entry.branch === undefined ? {} : { branch: entry.branch }),
+        };
+    }
+    const temporary = `${INDEX_FILE}.${process.pid}.tmp`;
+    try {
+        // 0700/0600: DATA_DIR also hosts history.jsonl / mouse-debug.log (0600
+        // files), so directory creation and the index itself (session titles
+        // quote the user's first input; branch names) must match that privacy
+        // posture. Creation only — pre-existing paths keep their current mode.
+        mkdirSync(DATA_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(temporary, JSON.stringify({ version: SCHEMA_VERSION, entries }), { mode: 0o600 });
+        renameSync(temporary, INDEX_FILE);
+        loadedStamp = indexStamp();
+        loadedIndex = new Map(index);
+    }
+    catch {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            // Nothing left to do; the cache stays as it was.
+        }
+    }
+}
+/**
+ * Record the git branch this install is on for a session.
+ *
+ * Kept here rather than in the log because it is not a fact about the session,
+ * it is a fact about how this machine used it — the same reason it is reported
+ * as "branch when last used" and omitted entirely for sessions that predate
+ * the note. Inventing a branch for them would be worse than showing none.
+ *
+ * @param sessionId - Session being used.
+ * @param branch - Current branch, or undefined to leave any note untouched.
+ */
+export function noteBranch(sessionId, branch) {
+    if (branch === undefined || branch.length === 0)
+        return;
+    const index = readIndex();
+    const existing = index.get(sessionId);
+    if (existing?.branch === branch)
+        return;
+    index.set(sessionId, { derived: existing?.derived, branch });
+    writeIndex(index);
+}
+/*
+ * Deliberately absent: a "forget this entry" call for the picker's delete, and
+ * a "patch this title" call for its rename. Listing prunes entries whose
+ * session no longer exists, and a renamed log has a new revision whose
+ * re-derivation reads the very title event the rename just appended — both
+ * paths already converge on the right answer, so a second mechanism to reach
+ * it could only disagree with the first.
+ */

package/lib/types/dsh-adapter/sessions/types.d.ts

@@ -0,0 +1,21 @@
+import type { SessionTitle } from '../../adapter/ports/channel-session.js';
+export type { SessionSummary, SessionKind, SessionTitle, TitleSource, PreviewEntry } from '../../adapter/ports/channel-session.js';
+/**
+ * Facts a bounded read can recover from one session log.
+ *
+ * No "last event time" here on purpose: for an append-only log the file's
+ * mtime says the same thing, is already read for {@link SessionSummary.bytes},
+ * and needs no cache entry of its own.
+ */
+export interface SessionDigest {
+    readonly title: SessionTitle | undefined;
+    /** False only after a complete successful scan proves no human message;
+     * true also keeps inconclusive reads visible and out of empty cleanup. */
+    readonly hasPrompt: boolean;
+    readonly model: string | undefined;
+    readonly label: string | undefined;
+    /** The whole log was covered, or the winning title was observed in the
+     * trailing window; no unseen middle event can supersede it. */
+    readonly titleComplete?: true;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/dsh-adapter/sessions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/sessions/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA+B,YAAY,EAA6B,MAAM,wCAAwC,CAAA;AAClI,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAA;AAGlI;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IACxC;8EAC0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC;mEAC+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAC9B"}

package/lib/types/dsh-adapter/sessions/types.js

@@ -0,0 +1 @@
+export {};

package/lib/types/dsh-adapter/settings-sections.d.ts

@@ -0,0 +1,48 @@
+import type { TuiSettingsSection } from '../adapter/ports/channel-settings.js';
+export type { TuiSettingsSection, TuiSettingsGroup, TuiSettingsField, TuiSettingsFieldKind, TuiSettingsFieldOption, TuiSettingsFieldWrite } from '../adapter/ports/channel-settings.js';
+/**
+ * Plugin settings-section extension seam for terminal front doors.
+ *
+ * The TUI owns the settings screen: rendering, staged editing, and the
+ * revision-fenced `settings.mutate` writes. Optional plugins declare WHAT is
+ * editable — a section over their settings namespace — without coupling the
+ * TUI to them, mirroring the web front door's `settings.plugin.item` slot
+ * (plugins ship cards; the host ships the chrome). Storage, validation and
+ * layering stay with the dsh settings service; this registry is display
+ * metadata only.
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+/** Host-only settings-section controls used by the TUI bootstrap/channel. */
+export interface TuiSettingsSectionsHost {
+    register(section: TuiSettingsSection): () => void;
+    list(): readonly TuiSettingsSection[];
+    section(ns: string): TuiSettingsSection | undefined;
+    subscribe(listener: () => void): () => void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiSettingsSections: TuiSettingsSectionsRuntime;
+    }
+}
+export declare const name = "dsh-tui-settings-sections";
+/**
+ * Small host-only registry; settings storage and validation remain owned by
+ * the dsh settings service (`ctx.settings`).
+ */
+export declare class TuiSettingsSectionsRuntime extends Service {
+    constructor(ctx: Context);
+    register(section: TuiSettingsSection): () => void;
+    /** Registered sections in registration order. */
+    list(): readonly TuiSettingsSection[];
+    /** The section registered for a namespace, if any. */
+    section(ns: string): TuiSettingsSection | undefined;
+    /**
+     * Subscribe to register/unregister events so an open settings screen can
+     * re-read the section list (a plugin (un)loading mid-session changes it).
+     */
+    subscribe(listener: () => void): () => void;
+}
+export declare function getHostSettingsSections(runtime: TuiSettingsSectionsRuntime | undefined): TuiSettingsSectionsHost | undefined;
+export declare function getLocalSettingsSectionsHost(ctx?: Context): TuiSettingsSectionsHost;
+export default TuiSettingsSectionsRuntime;
+//# sourceMappingURL=settings-sections.d.ts.map

package/lib/types/dsh-adapter/settings-sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-sections.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/settings-sections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAA2G,MAAM,sCAAsC,CAAA;AACvL,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAA;AACvL;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAWtD,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAA;IACjD,IAAI,IAAI,SAAS,kBAAkB,EAAE,CAAA;IACrC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAA;IACnD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC5C;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,mBAAmB,EAAE,0BAA0B,CAAA;KAChD;CACF;AAED,eAAO,MAAM,IAAI,8BAA8B,CAAA;AAE/C;;;GAGG;AACH,qBAAa,0BAA2B,SAAQ,OAAO;gBACzC,GAAG,EAAE,OAAO;IAsBxB,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;IAuBjD,iDAAiD;IACjD,IAAI,IAAI,SAAS,kBAAkB,EAAE;IASrC,sDAAsD;IACtD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IASnD;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CAU5C;AA6FD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,GAAG,uBAAuB,GAAG,SAAS,CAO5H;AAiDD,wBAAgB,4BAA4B,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAiBnF;AAED,eAAe,0BAA0B,CAAA"}

package/lib/types/dsh-adapter/settings-sections.js

@@ -0,0 +1,253 @@
+/**
+ * Plugin settings-section extension seam for terminal front doors.
+ *
+ * The TUI owns the settings screen: rendering, staged editing, and the
+ * revision-fenced `settings.mutate` writes. Optional plugins declare WHAT is
+ * editable — a section over their settings namespace — without coupling the
+ * TUI to them, mirroring the web front door's `settings.plugin.item` slot
+ * (plugins ship cards; the host ships the chrome). Storage, validation and
+ * layering stay with the dsh settings service; this registry is display
+ * metadata only.
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { activationFiber, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { vetSectionSecretRefs } from './credentialRefGuard.js';
+import { assertCapabilityShadowPolicy, defaultAdapterRuntime, } from '../adapter/kernel/runtime.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+export const name = 'dsh-tui-settings-sections';
+/**
+ * Small host-only registry; settings storage and validation remain owned by
+ * the dsh settings service (`ctx.settings`).
+ */
+export class TuiSettingsSectionsRuntime extends Service {
+    constructor(ctx) {
+        super(ctx, 'tuiSettingsSections');
+        compositionRoot(ctx);
+        const runtime = this;
+        const state = { sections: new Map(), owners: new Map(), listeners: new Set(), host: undefined, runtime: adapterRuntimeFor(ctx) };
+        state.host = Object.freeze({
+            register(section) {
+                return registerSection(runtime, section);
+            },
+            list() {
+                return [...settingsSectionStateFor(runtime).sections.values()];
+            },
+            section(ns) {
+                return settingsSectionStateFor(runtime).sections.get(ns);
+            },
+            subscribe(listener) {
+                return subscribeSections(runtime, listener);
+            },
+        });
+        settingsSectionStates.set(this, state);
+    }
+    register(section) {
+        assertCapabilityShadowPolicy('host.settings.register', settingsSectionStateFor(this).runtime.mode, settingsSectionStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiSettingsSections.register', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            throw new Error('dsh-tui: tuiSettingsSections.register requires a live activation');
+        // The service path is plugin-land. A plugin's secret field names its own
+        // credential ref, but nothing stopped it from naming a host-owned ref
+        // (DEEPSEEK_API_KEY / DEEPSEEK_* / DSH_*) and overwriting the user's
+        // shared credentials through a card that looks like plugin config.
+        // Reserved refs are rejected here; host-identity registrations (the
+        // owner-less host objects below) never pass through this method.
+        const vetted = vetSectionSecretRefs(section);
+        for (const rejection of vetted.rejected) {
+            this.ctx.logger.warn(`dsh-tui: settings section "${section.ns}" field "${rejection.path.join('.')}" was rejected: ` +
+                `credential ref "${rejection.ref}" is reserved by the host`);
+        }
+        const dispose = registerSection(this, vetted.section, owner);
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+    /** Registered sections in registration order. */
+    list() {
+        assertCapabilityShadowPolicy('host.settings.list', settingsSectionStateFor(this).runtime.mode, settingsSectionStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiSettingsSections.list', this);
+        const owner = activationFiber(caller);
+        return owner === undefined ? [] : [...settingsSectionStateFor(this).sections.entries()]
+            .filter(([ns]) => settingsSectionStateFor(this).owners.get(ns) === owner)
+            .map(([, section]) => section);
+    }
+    /** The section registered for a namespace, if any. */
+    section(ns) {
+        assertCapabilityShadowPolicy('host.settings.section', settingsSectionStateFor(this).runtime.mode, settingsSectionStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiSettingsSections.section', this);
+        const owner = activationFiber(caller);
+        const state = settingsSectionStateFor(this);
+        const normalized = ns.trim();
+        return owner !== undefined && state.owners.get(normalized) === owner ? state.sections.get(normalized) : undefined;
+    }
+    /**
+     * Subscribe to register/unregister events so an open settings screen can
+     * re-read the section list (a plugin (un)loading mid-session changes it).
+     */
+    subscribe(listener) {
+        assertCapabilityShadowPolicy('host.settings.subscribe', settingsSectionStateFor(this).runtime.mode, settingsSectionStateFor(this).runtime.slices);
+        const caller = requirePluginCaller(this.ctx, 'tuiSettingsSections.subscribe', this);
+        const owner = activationFiber(caller);
+        if (owner === undefined)
+            return () => { };
+        const dispose = subscribeSections(this, listener, owner);
+        bindCallerEffect(caller, dispose);
+        return dispose;
+    }
+}
+const settingsSectionStates = new WeakMap();
+function settingsSectionStateFor(runtime) {
+    const state = settingsSectionStates.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiSettingsSections host state is unavailable');
+    return state;
+}
+function registerSection(runtime, section, owner) {
+    const state = isSectionState(runtime) ? runtime : settingsSectionStateFor(runtime);
+    // Host sections use opaque Loader IDs; rewriting them breaks settings.mutate.
+    // Plugin-owned sections retain their existing namespace validation.
+    const ns = owner === undefined ? section.ns : section.ns.trim();
+    if (!ns || (owner !== undefined && !/^[a-z][a-z0-9_-]*$/u.test(ns))) {
+        throw new TypeError(`invalid TUI settings-section namespace: ${section.ns}`);
+    }
+    if (state.sections.has(ns))
+        throw new Error(`TUI settings section "${ns}" is already registered`);
+    const groupIds = new Set();
+    const groups = section.groups === undefined
+        ? undefined
+        : Object.freeze(section.groups.map(group => {
+            const id = group.id.trim();
+            if (!/^[a-z][a-z0-9_-]*$/u.test(id))
+                throw new TypeError(`invalid TUI settings group id: ${group.id}`);
+            if (groupIds.has(id))
+                throw new Error(`TUI settings group "${id}" is already declared in section "${ns}"`);
+            groupIds.add(id);
+            return Object.freeze({
+                ...group,
+                id,
+                descriptions: group.descriptions === undefined ? undefined : Object.freeze({ ...group.descriptions }),
+            });
+        }));
+    const fields = Object.freeze(section.fields.map(field => {
+        const group = field.group?.trim();
+        if (group !== undefined && !groupIds.has(group)) {
+            throw new TypeError(`TUI settings field "${field.path.join('.')}" references unknown group "${field.group}" in section "${ns}"`);
+        }
+        return Object.freeze({
+            ...field,
+            group,
+            path: Object.freeze([...field.path]),
+            descriptions: field.descriptions === undefined ? undefined : Object.freeze({ ...field.descriptions }),
+            hintDescriptions: field.hintDescriptions === undefined ? undefined : Object.freeze({ ...field.hintDescriptions }),
+            options: field.options === undefined
+                ? undefined
+                : Object.freeze(field.options.map(option => Object.freeze({ ...option, descriptions: option.descriptions === undefined ? undefined : Object.freeze({ ...option.descriptions }) }))),
+            secret: field.secret === undefined ? undefined : Object.freeze({ ...field.secret }),
+        });
+    }));
+    const normalized = Object.freeze({
+        ...section,
+        ns,
+        descriptions: section.descriptions === undefined ? undefined : Object.freeze({ ...section.descriptions }),
+        groups,
+        fields,
+    });
+    state.sections.set(ns, normalized);
+    if (owner !== undefined)
+        state.owners.set(ns, owner);
+    emitSections(state, owner);
+    return () => {
+        if (state.sections.get(ns) !== normalized)
+            return;
+        state.sections.delete(ns);
+        state.owners.delete(ns);
+        emitSections(state, owner);
+    };
+}
+function subscribeSections(runtime, listener, owner) {
+    const state = isSectionState(runtime) ? runtime : settingsSectionStateFor(runtime);
+    const entry = { owner, listener };
+    state.listeners.add(entry);
+    return () => {
+        state.listeners.delete(entry);
+    };
+}
+function emitSections(state, changedOwner) {
+    for (const entry of state.listeners) {
+        if (entry.owner !== undefined && entry.owner !== changedOwner)
+            continue;
+        entry.listener();
+    }
+}
+export function getHostSettingsSections(runtime) {
+    if (runtime === undefined)
+        return undefined;
+    try {
+        return settingsSectionStateFor(runtime).host ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSectionState(value) {
+    return value instanceof Map === false && 'sections' in value && 'listeners' in value;
+}
+/**
+ * In-package fallback registry: some real compositions dispose the
+ * `dsh-tui-settings-sections` service row right after it loads (the whole
+ * dsh-tui-* host-seam insert list is affected — see the issue-#183 skew
+ * family), leaving `ctx.get('tuiSettingsSections')` permanently undefined.
+ * The TUI's own section must not depend on that: plugin.ts registers into —
+ * and channel.ts reads from — this local host whenever the composition
+ * service is unavailable. Third-party sections still require the service
+ * row; the local host only carries the TUI's own section.
+ */
+let defaultLocalSectionsState;
+const localSectionsStates = new WeakMap();
+function localSectionsStateFor(ctx) {
+    if (ctx === undefined) {
+        // The no-context fallback is captured lazily on first use so importing
+        // this module never freezes an env-dependent policy before the embedding
+        // process has a chance to configure adapter mode.
+        defaultLocalSectionsState ??= {
+            runtime: defaultAdapterRuntime(),
+            sections: new Map(),
+            owners: new Map(),
+            listeners: new Set(),
+            host: undefined,
+        };
+        return defaultLocalSectionsState;
+    }
+    const root = compositionRoot(ctx);
+    let state = localSectionsStates.get(root);
+    if (state === undefined) {
+        state = {
+            runtime: adapterRuntimeFor(ctx),
+            sections: new Map(),
+            owners: new Map(),
+            listeners: new Set(),
+            host: undefined,
+        };
+        localSectionsStates.set(root, state);
+    }
+    return state;
+}
+export function getLocalSettingsSectionsHost(ctx) {
+    const state = localSectionsStateFor(ctx);
+    state.host ??= Object.freeze({
+        register(section) {
+            return registerSection(state, section);
+        },
+        list() {
+            return [...state.sections.values()];
+        },
+        section(ns) {
+            return state.sections.get(ns);
+        },
+        subscribe(listener) {
+            return subscribeSections(state, listener);
+        },
+    });
+    return state.host;
+}
+export default TuiSettingsSectionsRuntime;

package/lib/types/dsh-adapter/settingsEditor.d.ts

@@ -0,0 +1,100 @@
+import type { SettingsHost, SettingsNamespaceView } from '../adapter/ports/channel-settings.js';
+export type { SettingsHost, SettingsNamespaceView, SettingsPathOp } from '../adapter/ports/channel-settings.js';
+/**
+ * React-free form model behind the `/settings` screen (issue #165), mirroring
+ * the web front door's card-form.ts semantics: a section stages what the user
+ * types and writes it only on save — every settings write is a durable,
+ * revision-fenced `settings.mutate`, so a control that committed as it
+ * settled turned one edit into a write the user never asked for and could
+ * not preview; staged text makes what is on screen exactly what a save would
+ * store.
+ *
+ * A field shows its effective value — the user layer over the composition
+ * layer over the schema default — and whether the user layer carries it. That
+ * presence, not a value comparison, is what marks a field overridden: an
+ * override equal to the composition default is still an override.
+ *
+ * The kernel side (storage, schema validation, layering, revision fencing)
+ * stays with the dsh settings / credentials services; this module only
+ * translates between drafts and `mutate` path ops.
+ */
+import type { TuiSettingsField } from './settings-sections.js';
+/** One field as the screen renders it. */
+export interface SettingsFieldState {
+    /** Draft text the control renders. */
+    text: string;
+    /** Whether saving would leave a user-layer entry for this field. */
+    overridden: boolean;
+    /** Whether the draft is not a value this field accepts, blocking the save. */
+    invalid: boolean;
+}
+/** Form state every settings section shares. */
+export interface SettingsSectionShell {
+    /** False while the settings service serves no such namespace. */
+    available: boolean;
+    /** Whether the form holds edits that a save would write. */
+    dirty: boolean;
+    /** Whether any staged draft is invalid, which blocks the save. */
+    invalid: boolean;
+    /** Whether a save is in flight. */
+    saving: boolean;
+    /** Whether the last save failed; cleared by the next edit or save. */
+    failed: boolean;
+    /** Why the last save failed, when the writer said so (e.g. a reserved
+     * credential ref); shown verbatim so refusals are not just "failed". */
+    failureMessage?: string;
+}
+/** Read a nested value by path (array indexes as strings). */
+export declare function getPath(value: unknown, path: readonly string[]): unknown;
+/**
+ * Whether a value explicitly carries the path — its presence marks a user
+ * override, independent of the value stored there.
+ */
+export declare function hasPath(value: unknown, path: readonly string[]): boolean;
+/**
+ * The staged form over one settings namespace's declared fields. The screen
+ * re-seeds it from a fresh namespace view after every save and whenever the
+ * underlying document changes.
+ */
+export declare class SettingsForm {
+    private readonly host;
+    private readonly view;
+    private readonly fields;
+    private readonly edits;
+    saving: boolean;
+    failed: boolean;
+    failureMessage: string | undefined;
+    constructor(host: SettingsHost, view: SettingsNamespaceView | undefined, fields: readonly TuiSettingsField[]);
+    get available(): boolean;
+    /** The namespace view the form was seeded from (undefined = not served). */
+    get namespace(): SettingsNamespaceView | undefined;
+    field(field: TuiSettingsField): SettingsFieldState;
+    shell(): SettingsSectionShell;
+    /** Whether the field holds a staged (unsaved) edit. */
+    isStaged(field: TuiSettingsField): boolean;
+    /** Stage draft text for one field. */
+    edit(field: TuiSettingsField, text: string): void;
+    /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+    resetField(field: TuiSettingsField): void;
+    /** Drop every staged edit. */
+    discard(): void;
+    /** A new edit or save cycle retires the last failure's explanation. */
+    private clearFailure;
+    /** Whether any staged draft is invalid, which blocks the save. */
+    get invalid(): boolean;
+    /**
+     * Write every staged edit. Settings fields land as one revision-fenced
+     * `mutate` (one retry on a stale-revision conflict); credential fields
+     * write through the credentials seam. Resolves to whether every write
+     * landed — the caller re-seeds from a fresh namespace view afterwards.
+     *
+     * Only the edits THIS save snapshotted are cleared on success, and only
+     * when they are still the same edit: a draft typed while the write was in
+     * flight is a newer object and survives — it was never written, so it must
+     * not be silently dropped.
+     */
+    save(): Promise<boolean>;
+    /** Whether any layer supplies the credential a secret field addresses. */
+    credentialConfigured(field: TuiSettingsField): Promise<boolean>;
+}
+//# sourceMappingURL=settingsEditor.d.ts.map

package/lib/types/dsh-adapter/settingsEditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settingsEditor.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/settingsEditor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,qBAAqB,EAAkB,MAAM,sCAAsC,CAAA;AAC/G,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAA;AAC/G;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAyB,MAAM,wBAAwB,CAAA;AAErF,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,UAAU,EAAE,OAAO,CAAA;IACnB,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAA;IAClB,4DAA4D;IAC5D,KAAK,EAAE,OAAO,CAAA;IACd,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAA;IAChB,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAA;IACf,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAA;IACf;4EACwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAWxE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAOxE;AAiDD;;;;GAIG;AACH,qBAAa,YAAY;IAOrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,MAAM,UAAQ;IACd,MAAM,UAAQ;IACd,cAAc,EAAE,MAAM,GAAG,SAAS,CAAY;gBAG3B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,qBAAqB,GAAG,SAAS,EACvC,MAAM,EAAE,SAAS,gBAAgB,EAAE;IAGtD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,4EAA4E;IAC5E,IAAI,SAAS,IAAI,qBAAqB,GAAG,SAAS,CAEjD;IAED,KAAK,CAAC,KAAK,EAAE,gBAAgB,GAAG,kBAAkB;IAuBlD,KAAK,IAAI,oBAAoB;IAe7B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO;IAI1C,sCAAsC;IACtC,IAAI,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAKjD,gFAAgF;IAChF,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAKzC,8BAA8B;IAC9B,OAAO,IAAI,IAAI;IAKf,uEAAuE;IACvE,OAAO,CAAC,YAAY;IAKpB,kEAAkE;IAClE,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;;;;OAUG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAsD9B,0EAA0E;IAC1E,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAGhE"}