@deepseek-harness-tui/dsh-tui 0.14.0 → 0.15.0

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

@@ -2,6 +2,8 @@ import { addUsageToCostBuckets, cloneCostBuckets, emptyCostBuckets, isDeepSeekOf
 import { toolResultPayload } from './compat/messages.js';
 const MAX_OUTPUT_EVENTS = 160;
 const MAX_OUTPUT_LINES = 160;
+/** Keyed labels parked before their row exists (see `earlyLabels`). */
+const MAX_EARLY_LABELS = 64;
 export class SubagentActivityStore {
     states = new Map();
     sessionToAgent = new Map();
@@ -13,6 +15,17 @@ export class SubagentActivityStore {
     costUnpriced = emptyCostBuckets();
     /** 每个 agent 已消费的最大 durable 事件 seq（同一事件重投不重复计费）。 */
     costSeq = new Map();
+    /** 描述的来源。spawn 首帧的描述来自一条**无身份**的 FIFO 队列（并发派发
+     *  时可能是别的 child 的），只有 childId-keyed 的权威 label
+     *  （`subagent/catalog`、子会话 `subagent/descriptor`）能定案：`bound`
+     *  之后不再改写，`queue`/`placeholder` 允许被 label 覆盖。 */
+    descriptionSource = new Map();
+    /** keyed label 可能比它那一行先到：子会话的 `subagent/descriptor` 在会话
+     *  链接建立之前就已投递。丢掉它，这一行就只剩队列猜出来的名字，而外部
+     *  子代理上游不写 catalog ⇒ 没有第二条 keyed 事实来救，永久错名。先寄存在
+     *  这里，建行时直接当描述用：keyed 事实不因到达先后而失效。有界，理由同
+     *  队列（没人建行时不能无界增长）。 */
+    earlyLabels = new Map();
     commitLine(agentId, kind, text) {
         const state = this.states.get(agentId);
         if (!state)
@@ -29,11 +42,26 @@ export class SubagentActivityStore {
     }
     onSpawned(agentId, provider = 'subagent', model, info = {}) {
         const existing = this.states.get(agentId);
+        // A term off the identity-less spawn queue may belong to a concurrent
+        // delegation, so it never overrides a description a keyed fact already
+        // settled. The caller still consumes (shifts) the term either way — the
+        // FIFO has no identity to hand back, and leaving it at the head would only
+        // misalign the next spawn.
+        const fromQueue = info.descriptionFromQueue === true;
+        const description = fromQueue && this.descriptionSource.get(agentId) === 'bound' ? undefined : info.description;
+        // A keyed label that outran its row (see `earlyLabels`) carries the same
+        // authority as a live one: the row is born settled, and the queue term the
+        // same spawn consumed is dropped instead of shown.
+        const keyed = this.earlyLabels.get(agentId);
+        if (keyed !== undefined)
+            this.earlyLabels.delete(agentId);
+        const settled = keyed ?? description;
+        const source = keyed !== undefined ? 'bound' : description === undefined ? 'placeholder' : fromQueue ? 'queue' : 'bound';
         if (!existing) {
             this.states.set(agentId, {
                 agentId,
                 runId: info.runId ?? agentId,
-                description: info.description ?? `${provider} task`,
+                description: settled ?? `${provider} task`,
                 provider,
                 model: model ?? info.model ?? provider,
                 effort: info.effort,
@@ -47,6 +75,7 @@ export class SubagentActivityStore {
                 toolCalls: [],
                 ...(info.parentAgentId === undefined ? {} : { parentAgentId: info.parentAgentId }),
             });
+            this.descriptionSource.set(agentId, source);
             this.notify();
             return;
         }
@@ -54,7 +83,11 @@ export class SubagentActivityStore {
         // new epoch announces a NEW runId (the host's `subagent/start` pairing
         // key). A runId change therefore opens a fresh run: the previous epoch's
         // terminal state, timing, output and tools must not leak into it. The
-        // same runId re-announced only refreshes display metadata.
+        // description is the one thing a new epoch does not own *once a keyed
+        // label settled it*: that label outranks the queue and survives every
+        // epoch (see the guard above), while a row still living on a queue guess
+        // takes the new epoch's term like any other fresh run. The same runId
+        // re-announced only refreshes display metadata.
         if (info.runId !== undefined && info.runId !== existing.runId) {
             this.streams.delete(agentId);
             existing.runId = info.runId;
@@ -69,7 +102,9 @@ export class SubagentActivityStore {
             existing.outputEvents = [];
             existing.toolCalls = [];
             existing.tokens = undefined;
-            existing.description = info.description ?? existing.description;
+            existing.description = settled ?? existing.description;
+            if (settled !== undefined)
+                this.descriptionSource.set(agentId, source);
             existing.local = info.local ?? existing.local;
             existing.provider = provider;
             existing.model = model ?? existing.model;
@@ -81,8 +116,10 @@ export class SubagentActivityStore {
         else {
             existing.provider = provider;
             existing.model = model ?? existing.model;
-            if (info.description !== undefined)
-                existing.description = info.description;
+            if (settled !== undefined) {
+                existing.description = settled;
+                this.descriptionSource.set(agentId, source);
+            }
             if (info.local !== undefined)
                 existing.local = info.local;
             if (info.parentAgentId !== undefined && existing.parentAgentId === undefined)
@@ -90,6 +127,43 @@ export class SubagentActivityStore {
         }
         this.notify();
     }
+    /** Park a keyed label whose row does not exist yet — a child session's
+     *  `subagent/descriptor` can be published before the host's spawn edge, and
+     *  dropping it there would leave the row with the identity-less queue's
+     *  guess and no second keyed fact to correct it (an external child gets no
+     *  catalog). `onSpawned` adopts it when the row is created. Bounded: when
+     *  full, the oldest parked label goes first — the least likely to still be
+     *  waiting for its row. */
+    holdKeyedLabel(agentId, label) {
+        if (typeof label !== 'string' || label === '')
+            return;
+        if (!this.earlyLabels.has(agentId) && this.earlyLabels.size >= MAX_EARLY_LABELS) {
+            const oldest = this.earlyLabels.keys().next().value;
+            if (oldest !== undefined)
+                this.earlyLabels.delete(oldest);
+        }
+        this.earlyLabels.set(agentId, label);
+    }
+    /** Bind the authoritative description of one child (a `subagent/catalog`
+     *  label or a child session's own `subagent/descriptor`). The identity-less
+     *  spawn queue may have handed this row a concurrent delegation's term, so
+     *  the keyed fact wins, once, until it is the source of truth for this row.
+     *  Returns whether the displayed description changed. */
+    describeFromLabel(agentId, label) {
+        if (typeof label !== 'string' || label === '')
+            return false;
+        // A row-less call has no display to correct: the projection parks such a
+        // label before it gets here (`holdKeyedLabel`) and the row adopts it when
+        // it is created.
+        const state = this.states.get(agentId);
+        if (state === undefined || this.descriptionSource.get(agentId) === 'bound')
+            return false;
+        this.descriptionSource.set(agentId, 'bound');
+        if (state.description === label)
+            return false;
+        state.description = label;
+        return true;
+    }
     /** Durable discovery (`subagent/catalog`, workflow member events, registry
      * back-fill): register a child WITHOUT disturbing an already-tracked run.
      * `live` marks a child the agents registry currently holds, which keeps the
@@ -99,16 +173,25 @@ export class SubagentActivityStore {
         const existing = this.states.get(agentId);
         if (existing !== undefined) {
             // A bus edge usually created the row first; the durable catalog fact
-            // still carries the one thing the edge never knows — the mode.
+            // still carries the two things the edge never knows — the mode, and the
+            // childId-keyed label that a queue-derived description only guessed at.
+            let changed = false;
             if (info.mode !== undefined && existing.mode === undefined) {
                 existing.mode = info.mode;
-                this.notify();
+                changed = true;
             }
+            if (this.describeFromLabel(agentId, info.label))
+                changed = true;
+            if (changed)
+                this.notify();
             return;
         }
+        // An empty label is not a fact: the row keeps a visible placeholder that a
+        // later real label can still replace.
+        const label = typeof info.label === 'string' && info.label !== '' ? info.label : undefined;
         this.states.set(agentId, {
             agentId,
-            description: info.label ?? `${info.provider ?? 'subagent'} task`,
+            description: label ?? `${info.provider ?? 'subagent'} task`,
             provider: info.provider ?? 'subagent',
             model: info.model ?? info.provider,
             status: info.live ? 'running' : 'unknown',
@@ -119,6 +202,7 @@ export class SubagentActivityStore {
             outputEvents: [],
             toolCalls: [],
         });
+        this.descriptionSource.set(agentId, label === undefined ? 'placeholder' : 'bound');
         this.notify();
     }
     linkSession(agentId, session) {
@@ -130,6 +214,11 @@ export class SubagentActivityStore {
     }
     getSubagentIdBySession(session) { return this.sessionToAgent.get(session); }
     has(agentId) { return this.states.has(agentId); }
+    /** The run key of one tracked child: its current epoch's key, or `undefined`
+     *  when the row is tracked but has no run fact yet (a durable discovery row
+     *  carries none). That is the same value an untracked child yields, so a
+     *  caller that must tell the two apart asks `has()` as well. */
+    runIdOf(agentId) { return this.states.get(agentId)?.runId; }
     appendOutput(agentId, text, kind = 'text') {
         const state = this.states.get(agentId);
         if (!state || !text)
@@ -303,6 +392,14 @@ export class SubagentActivityStore {
                 }
                 break;
             }
+            case 'subagent/descriptor': {
+                // The child session's own durable self-description: the same keyed
+                // label the parent catalog carries, usable once the session link
+                // exists.
+                if (this.describeFromLabel(agentId, data.label))
+                    this.notify();
+                break;
+            }
             default:
                 break;
         }
@@ -313,6 +410,9 @@ export class SubagentActivityStore {
         if (!state)
             return;
         Object.assign(state, partial);
+        // A description handed in directly is authoritative, never a queue guess.
+        if (partial.description !== undefined)
+            this.descriptionSource.set(agentId, 'bound');
         this.notify();
     }
     /** One-line preview of a tool-result content block (text or item list). */
@@ -447,6 +547,8 @@ export class SubagentActivityStore {
         this.costByModel.clear();
         this.costUnpriced = emptyCostBuckets();
         this.costSeq.clear();
+        this.descriptionSource.clear();
+        this.earlyLabels.clear();
         this.notify();
     }
     snapshot() { return Array.from(this.states.values()).map(state => ({ ...state, output: [...state.output], outputEvents: [...state.outputEvents], toolCalls: state.toolCalls.map(tool => ({ ...tool })), tokens: state.tokens ? { ...state.tokens } : undefined })); }

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

@@ -0,0 +1,57 @@
+/**
+ * The `dsh-tui` settings namespace served from the TUI's own document
+ * (../tuiSettingsFile.ts) instead of the DSH profile, so every kernel reads and writes one user layer. Same shape as
+ * the settings service the plugin and channel already consume; every other
+ * namespace goes to `delegate` (the host's settings service, when mounted).
+ */
+import type Schema from '@deepseek-ai/schemastery';
+import type { SettingsNamespaceWarning } from '../adapter/ports/channel-settings.js';
+type PathOp = {
+    readonly op: 'set';
+    readonly path: readonly string[];
+    readonly value: unknown;
+} | {
+    readonly op: 'unset';
+    readonly path: readonly string[];
+};
+interface Descriptor {
+    readonly ns: string;
+    readonly revision: number;
+    readonly applies: 'live' | 'restart';
+    readonly value?: unknown;
+    readonly user?: unknown;
+    /** A fault in the settings document itself, when there is one. */
+    readonly warning?: SettingsNamespaceWarning;
+}
+/** The settings service as the plugin and the channel consume it. */
+export interface TuiSettingsService {
+    register<T>(ns: string, schema: Schema<T>): {
+        get(): T;
+        watch(callback: (next: T) => void): () => void;
+    };
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): readonly Descriptor[];
+    mutate(ns: string, ops: readonly PathOp[], expectedRevision?: number): Promise<void>;
+    get(ns: string): unknown;
+}
+/** What the composite forwards other namespaces to (structural). */
+export interface DelegateSettings {
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): readonly Descriptor[];
+    mutate(ns: string, ops: readonly PathOp[], expectedRevision?: number): Promise<void>;
+    get?(ns: string): unknown;
+}
+export declare function createTuiSettingsService(input: {
+    /** The namespace this service owns (the plugin's settings namespace). */
+    readonly ns: string;
+    readonly file?: string;
+    readonly profile: string;
+    /** The editable Config keys (what the import may take from the profile). */
+    readonly keys: readonly string[];
+    /** Read per call: the host's own settings service may register late. */
+    readonly delegate?: () => DelegateSettings | undefined;
+}): TuiSettingsService;
+export {};
+//# sourceMappingURL=tui-settings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tui-settings.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/tui-settings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,MAAM,MAAM,0BAA0B,CAAA;AAOlD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAA;AAEpF,KAAK,MAAM,GACP;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACjF;IAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAA;AAE9D,UAAU,UAAU;IAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,wBAAwB,CAAA;CAC5C;AAED,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG;QAAE,GAAG,IAAI,CAAC,CAAC;QAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;KAAE,CAAA;IACxG,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,UAAU,EAAE,CAAA;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,UAAU,EAAE,CAAA;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,MAAM,EAAE,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACpF,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;CAC1B;AA4FD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,gBAAgB,GAAG,SAAS,CAAA;CACvD,GAAG,kBAAkB,CAsFrB"}

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

@@ -0,0 +1,199 @@
+import { logForDebugging } from '../utils/debug.js';
+import { isRecord } from '../backends/shared/jsonl.js';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { withFileLock } from '@deepseek-ai/dsh-atomic-write';
+import { backupUnreadableTuiSettings, createTuiSettings, mergeSettingsLayers, profilePatchPath, readLegacyTuiSettings, readProfileTuiSettings, readTuiSettings, TUI_SETTINGS_FILE, writeTuiSettings } from '../tuiSettingsFile.js';
+/** A stale-revision write, in the error shape the settings screen retries on. */
+class SettingsConflictError extends Error {
+    code = 'SETTINGS_CONFLICT';
+}
+/** Apply one path op to a detached sparse layer; empty parents are pruned. */
+function applySettingsOp(layer, op) {
+    const [head, ...rest] = op.path;
+    if (head === undefined) {
+        return op.op === 'set' && isRecord(op.value) ? { ...op.value } : {};
+    }
+    const next = { ...layer };
+    if (rest.length === 0) {
+        if (op.op === 'set')
+            next[head] = op.value;
+        else
+            delete next[head];
+        return next;
+    }
+    const child = isRecord(layer[head]) ? layer[head] : {};
+    const updated = applySettingsOp(child, op.op === 'set' ? { op: 'set', path: rest, value: op.value } : { op: 'unset', path: rest });
+    if (Object.keys(updated).length === 0)
+        delete next[head];
+    else
+        next[head] = updated;
+    return next;
+}
+/**
+ * The first boot without a document imports the profile patch's `dsh-tui`
+ * row and an older host's `settings.yaml` section (once per source; only the
+ * first of concurrent imports is written). A pending `settings.yaml` is the
+ * user layer above the row, as on those hosts; one DSH already moved into the
+ * patch (`.imported`) sits beneath it, since the patch may be newer. A later
+ * boot under a profile whose patch the document was not imported from lays
+ * that row beneath the user layer (explicit values always win) and records
+ * the new source — the first profile no longer pins the document forever.
+ */
+function loadTuiSettings(input) {
+    const file = input.file ?? TUI_SETTINGS_FILE;
+    const existing = readTuiSettings(file);
+    if (existing !== undefined) {
+        const patch = profilePatchPath(input.profile);
+        // 'none' names no source; anything else is a list of imported paths.
+        const sources = existing.imported?.from === undefined || existing.imported.from === 'none' ? [] : existing.imported.from.split(', ');
+        // An unreadable document keeps this boot's copy; one already carrying
+        // this profile's patch (or none at all, `imported`-less) is adopted as is.
+        if (existing.imported === undefined || existing.imported.from === 'unreadable' || sources.includes(patch))
+            return existing;
+        const row = readProfileTuiSettings(patch, input.keys);
+        if (row === undefined)
+            return existing;
+        const reimported = (document) => ({
+            version: 1,
+            values: mergeSettingsLayers(row, document.values),
+            imported: { from: `${document.imported?.from}, ${patch}`, at: Date.now() },
+        });
+        try {
+            // Re-read as late as possible: another process may have written since
+            // the first read, and its keys must survive the merge. Not under the
+            // writer lock — like the first import, the merge only ever adds keys.
+            const fresh = readTuiSettings(file) ?? existing;
+            if (fresh.imported === undefined || fresh.imported.from === 'unreadable' || (fresh.imported.from !== 'none' && fresh.imported.from.split(', ').includes(patch)))
+                return fresh;
+            const next = reimported(fresh);
+            writeTuiSettings(next, file);
+            return next;
+        }
+        catch (error) {
+            // Still usable for this boot; the next one retries the re-import.
+            logForDebugging(`dsh-tui: settings re-import for "${input.profile}" could not be saved (${error instanceof Error ? error.message : String(error)})`);
+            return reimported(existing);
+        }
+    }
+    const patch = profilePatchPath(input.profile);
+    const row = readProfileTuiSettings(patch, input.keys);
+    const legacy = readLegacyTuiSettings(input.ns, input.keys);
+    const values = legacy === undefined
+        ? row ?? {}
+        : legacy.pending ? mergeSettingsLayers(row ?? {}, legacy.values) : mergeSettingsLayers(legacy.values, row ?? {});
+    const sources = [...(row === undefined ? [] : [patch]), ...(legacy === undefined ? [] : [legacy.from])];
+    const document = { version: 1, values, imported: { from: sources.length === 0 ? 'none' : sources.join(', '), at: Date.now() } };
+    try {
+        // Two first launches race here: the later one adopts the document the
+        // earlier one created rather than replacing it.
+        if (!createTuiSettings(document, file))
+            return readTuiSettings(file) ?? document;
+    }
+    catch (error) {
+        // Still usable for this boot; the next one retries the import.
+        logForDebugging(`dsh-tui: settings import could not be saved (${error instanceof Error ? error.message : String(error)})`);
+    }
+    return document;
+}
+export function createTuiSettingsService(input) {
+    const file = input.file ?? TUI_SETTINGS_FILE;
+    let document = loadTuiSettings({ file, ns: input.ns, profile: input.profile, keys: input.keys });
+    /** A fault in the document, shown through `describe` so callers (the
+     * settings screen's badges) can see it without a debug flag. */
+    let warning = document.imported?.from === 'unreadable' ? { id: 'unreadable' } : undefined;
+    let revision = 0;
+    let schema;
+    const watchers = new Set();
+    /** The resolved value: the user layer through the registered schema's
+     *  defaults (an invalid layer resolves to the defaults alone). */
+    const resolved = () => {
+        if (schema === undefined)
+            return document.values;
+        try {
+            return schema(document.values);
+        }
+        catch (error) {
+            logForDebugging(`dsh-tui: settings.json does not validate (${error instanceof Error ? error.message : String(error)}); using defaults`);
+            try {
+                return schema({});
+            }
+            catch {
+                return {};
+            }
+        }
+    };
+    const own = { ns: input.ns, revision: 0, applies: 'live' };
+    const describeOwn = () => ({ ...own, revision, value: resolved(), user: document.values, ...(warning === undefined ? {} : { warning }) });
+    return {
+        register(ns, registered) {
+            if (ns !== input.ns)
+                throw new Error(`dsh-tui: settings namespace "${ns}" is not served here`);
+            schema = registered;
+            return {
+                get: () => resolved(),
+                watch(callback) {
+                    const watcher = (next) => { callback(next); };
+                    watchers.add(watcher);
+                    return () => { watchers.delete(watcher); };
+                },
+            };
+        },
+        describe(options) {
+            const others = input.delegate?.()?.describe(options).filter(row => row.ns !== input.ns) ?? [];
+            return [describeOwn(), ...others];
+        },
+        async mutate(ns, ops, expectedRevision) {
+            if (ns !== input.ns) {
+                const delegate = input.delegate?.();
+                if (delegate === undefined)
+                    throw new Error(`dsh-tui: no settings namespace "${ns}"`);
+                return delegate.mutate(ns, ops, expectedRevision);
+            }
+            if (expectedRevision !== undefined && expectedRevision !== revision) {
+                throw new SettingsConflictError(`dsh-tui: settings changed (revision ${revision}, expected ${expectedRevision})`);
+            }
+            // Apply onto the file as it is now: another dsh-tui process may have
+            // written since boot (an unreadable file keeps this process's copy).
+            // The lock spans the re-read and the replace, so concurrent writers of
+            // different keys both land (its `<file>.lock` sibling needs the directory).
+            mkdirSync(dirname(file), { recursive: true });
+            await withFileLock(file, async () => {
+                const latest = readTuiSettings(file);
+                if (latest !== undefined && latest.imported?.from !== 'unreadable') {
+                    document = latest;
+                }
+                else if (latest?.imported?.from === 'unreadable') {
+                    // The first write over a document this boot could not parse must
+                    // never destroy the original bytes: keep them beside the file (a
+                    // failed backup aborts the write — the settings screen reports it).
+                    const backup = backupUnreadableTuiSettings(file);
+                    warning = { id: 'recovered', backup };
+                    logForDebugging(`dsh-tui: settings.json was unreadable; the original bytes were kept at ${backup}`);
+                }
+                const values = ops.reduce((layer, op) => applySettingsOp(layer, op), { ...document.values });
+                // The unreadable marker describes the file as read, not as rewritten.
+                const { imported, ...rest } = document;
+                const next = { ...rest, values, ...(imported === undefined || imported.from === 'unreadable' ? {} : { imported }) };
+                writeTuiSettings(next, file);
+                document = next;
+            });
+            revision += 1;
+            const value = resolved();
+            for (const watcher of [...watchers]) {
+                try {
+                    watcher(value);
+                }
+                catch (error) {
+                    logForDebugging(`dsh-tui: settings watcher failed (${error instanceof Error ? error.message : String(error)})`);
+                }
+            }
+        },
+        get(ns) {
+            if (ns === input.ns)
+                return resolved();
+            const delegate = input.delegate?.();
+            return delegate?.get?.(ns) ?? delegate?.describe().find(row => row.ns === ns)?.value;
+        },
+    };
+}

package/lib/types/effortPrefs.d.ts

@@ -17,9 +17,12 @@ export declare function readEffortPref(dir?: string): string | undefined;
  * Default reasoning-effort precedence for sessions that do not carry their
  * own choice: the /settings 默认推理强度 user layer (`settings.yaml
  * dsh-tui.effortDefault`; the plugin folds the `auto` option to undefined
- * before calling), then the cordis.yml `effort` pin, then this persisted
- * `/effort` file, then the adapter/model default (undefined). Mirrors the
- * lang chain (settings user layer > cordis.yml > lang.json).
+ * before calling), then this persisted `/effort` file — the level the last
+ * session actually ran on — then the cordis.yml `effort` value, which is the
+ * deployment DEFAULT beneath the user's standing choice, then the
+ * adapter/model default (undefined). Mirrors the lang chain for its first
+ * two layers (settings user layer > lang.json) and the last-used rule the
+ * model route follows.
  * @param settingsDefault - settings user-layer level (undefined = auto).
  * @param configured - cordis.yml `effort` value, if any.
  * @param persisted - The /effort choice, if any.

package/lib/types/effortPrefs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effortPrefs.d.ts","sourceRoot":"","sources":["../../src/effortPrefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAkB,GAAG,MAAM,GAAG,SAAS,CAS1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,GAAG,SAAS,CAEpB;AAOD;;;;;+EAK+E;AAC/E,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAA8C,CAAA;AAElG;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAgBtG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAQhF"}
+{"version":3,"file":"effortPrefs.d.ts","sourceRoot":"","sources":["../../src/effortPrefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAkB,GAAG,MAAM,GAAG,SAAS,CAS1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,MAAM,GAAG,SAAS,EACnC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,GAAG,SAAS,CAEpB;AAOD;;;;;+EAK+E;AAC/E,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAA8C,CAAA;AAElG;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAgBtG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAE,MAAkB,GAAG,OAAO,CAQhF"}

package/lib/types/effortPrefs.js

@@ -32,16 +32,19 @@ export function readEffortPref(dir = PREFS_DIR) {
  * Default reasoning-effort precedence for sessions that do not carry their
  * own choice: the /settings 默认推理强度 user layer (`settings.yaml
  * dsh-tui.effortDefault`; the plugin folds the `auto` option to undefined
- * before calling), then the cordis.yml `effort` pin, then this persisted
- * `/effort` file, then the adapter/model default (undefined). Mirrors the
- * lang chain (settings user layer > cordis.yml > lang.json).
+ * before calling), then this persisted `/effort` file — the level the last
+ * session actually ran on — then the cordis.yml `effort` value, which is the
+ * deployment DEFAULT beneath the user's standing choice, then the
+ * adapter/model default (undefined). Mirrors the lang chain for its first
+ * two layers (settings user layer > lang.json) and the last-used rule the
+ * model route follows.
  * @param settingsDefault - settings user-layer level (undefined = auto).
  * @param configured - cordis.yml `effort` value, if any.
  * @param persisted - The /effort choice, if any.
  * @returns The winning level id, or undefined for the adapter default.
  */
 export function resolveEffortDefault(settingsDefault, configured, persisted) {
-    return settingsDefault ?? configured ?? persisted;
+    return settingsDefault ?? persisted ?? configured;
 }
 /** Standard effort-tier order, weakest to strongest (`xhigh` sits between
  * `high` and `max`, matching the ladder the kernels accept — see

package/lib/types/hostEntryRoute.d.ts

@@ -0,0 +1,18 @@
+import { type KernelBackendId } from './kernelPrefs.js';
+export declare function hostProfile(env?: NodeJS.ProcessEnv): string;
+/** The `backend` the profile patch's dsh-tui row pins, if any (the Config
+ *  row a DSH composition would read). `'dynamic'`: a `!!js` expression only
+ *  the profile's own Loader can evaluate; one that only forwards
+ *  DSH_TUI_BACKEND is no pin. */
+export declare function configuredBackend(profile: string, patchFile?: string): KernelBackendId | 'dynamic' | undefined;
+/** Whether the entry hands this launch to `dsh --profile`: a dynamic Config
+ *  row decides the kernel there, unless a kernel-switch handoff outranks it. */
+export declare function delegatesToProfile(configured: KernelBackendId | 'dynamic' | undefined, env?: NodeJS.ProcessEnv): boolean;
+/** The kernel this launch boots on, ranked as in the plugin (handoff → Config
+ *  row → DSH_TUI_BACKEND → kernel.json → dsh). An id that is not installed
+ *  falls back to dsh like a typo, so the entry never mounts an unloadable kernel. */
+export declare function entryKernel(env?: NodeJS.ProcessEnv, input?: {
+    readonly configured?: KernelBackendId | 'dynamic';
+    readonly memoryFile?: string;
+}): KernelBackendId;
+//# sourceMappingURL=hostEntryRoute.d.ts.map

package/lib/types/hostEntryRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostEntryRoute.d.ts","sourceRoot":"","sources":["../../src/hostEntryRoute.ts"],"names":[],"mappings":"AAMA,OAAO,EAAwF,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAO7I,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGxE;AAMD;;;iCAGiC;AACjC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAkC,GAAG,eAAe,GAAG,SAAS,GAAG,SAAS,CAYzI;AAED;gFACgF;AAChF,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,GAAG,SAAS,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAErI;AAED;;qFAEqF;AACrF,wBAAgB,WAAW,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,KAAK,GAAE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CACxB,GAAG,eAAe,CAUvB"}

package/lib/types/hostEntryRoute.js

@@ -0,0 +1,57 @@
+/**
+ * Which kernel the package's entry boots (docs/standalone-host-design.md).
+ * The launcher repeats the cheap half inline; the entry decides again here
+ * with the profile patch's Config row, which only it can afford to read.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { KERNEL_SWITCH_HANDOFF_ENV, parseBackendId, readKernelPrefs, resolveRememberedBackend } from './kernelPrefs.js';
+import { isRegisteredBackend, parseBackendChoice } from './dsh-adapter/backend-registry.js';
+import { profilePatchPath, readProfileTuiSettings } from './tuiSettingsFile.js';
+/** The profile the launcher would have started (`dsh --profile <name>`). */
+const HOST_PROFILE_ENV = 'DSH_TUI_PROFILE';
+export function hostProfile(env = process.env) {
+    const name = env[HOST_PROFILE_ENV]?.trim();
+    return name === undefined || name === '' ? 'dsh-tui' : name;
+}
+/** An expression that only forwards DSH_TUI_BACKEND (the bundle row's own
+ *  form): the entry already ranks that variable, right below the row. */
+const ENV_BACKEND_EXPRESSION = /^\s*process\.env\.DSH_TUI_BACKEND\s*(?:(?:\|\||\?\?)\s*undefined\s*)?$/u;
+/** The `backend` the profile patch's dsh-tui row pins, if any (the Config
+ *  row a DSH composition would read). `'dynamic'`: a `!!js` expression only
+ *  the profile's own Loader can evaluate; one that only forwards
+ *  DSH_TUI_BACKEND is no pin. */
+export function configuredBackend(profile, patchFile = profilePatchPath(profile)) {
+    // Most patches never mention it: skip the YAML parse then.
+    try {
+        if (!existsSync(patchFile) || !readFileSync(patchFile, 'utf8').includes('backend'))
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const expressions = new Map();
+    const backend = readProfileTuiSettings(patchFile, ['backend'], expressions)?.backend;
+    const expression = expressions.get('backend');
+    if (expression !== undefined)
+        return ENV_BACKEND_EXPRESSION.test(expression) ? undefined : 'dynamic';
+    return parseBackendChoice(backend);
+}
+/** Whether the entry hands this launch to `dsh --profile`: a dynamic Config
+ *  row decides the kernel there, unless a kernel-switch handoff outranks it. */
+export function delegatesToProfile(configured, env = process.env) {
+    return configured === 'dynamic' && parseBackendId(env[KERNEL_SWITCH_HANDOFF_ENV]) === undefined;
+}
+/** The kernel this launch boots on, ranked as in the plugin (handoff → Config
+ *  row → DSH_TUI_BACKEND → kernel.json → dsh). An id that is not installed
+ *  falls back to dsh like a typo, so the entry never mounts an unloadable kernel. */
+export function entryKernel(env = process.env, input = {}) {
+    const handoff = parseBackendId(env[KERNEL_SWITCH_HANDOFF_ENV]);
+    const memory = readKernelPrefs(input.memoryFile).backend;
+    return resolveRememberedBackend({
+        ...(handoff === undefined ? {} : { handoff }),
+        ...(input.configured === undefined || input.configured === 'dynamic' ? {} : { configured: input.configured }),
+        envRaw: env.DSH_TUI_BACKEND,
+        envKnown: isRegisteredBackend,
+        memory: isRegisteredBackend(memory) ? memory : undefined,
+    });
+}