dsh-loop-engine 0.1.5-rc3 → 0.1.5-rc4

package/lib/types/client/session-engine.d.ts

@@ -0,0 +1,474 @@
+/**
+ * Per-session engine, browser half: read the engine a session actually runs
+ * from the plugin's OWN Remote, and switch it through that same Remote.
+ *
+ * The engine a session runs is NOT a client-cache fact, and reading one as if it
+ * were is the bug this module exists to prevent. The harness hands a page a
+ * projection HINT per session (`@deepseek-ai/dsh-api-session-controller`'s
+ * `projectionsFor()` returns `SessionProjectionHints`: "every currently cached
+ * wire value", partial by its own documentation), and its `agentPreset` cell
+ * answers a different question than "what does this session run": a session may
+ * switch engine while it is blank (and, with this plugin, at any time), and that
+ * choice lives in the plugin's own record while the session header keeps naming
+ * the preset the session was CREATED with. A page reading the hint therefore
+ * shows a claude-code session that switched to pi — and the engine it actually
+ * runs — as Claude Code, the misreport this plugin shipped a production incident
+ * for.
+ *
+ * So the browser half asks the host instead:
+ * `remote.loopEngine.engine({ sessionId })` to read, and
+ * `remote.loopEngine.select({ sessionId, engine })` to switch — the endpoints
+ * `src/engine-remote.ts` serves from the same read the router routes on. Nothing
+ * is derived here: the three-state arrives decided, and a refused switch arrives
+ * with the host's own reason.
+ *
+ * This module is deliberately React-free: the cache, the contribution, and the
+ * switch are plain logic, so they run in node under its own spec
+ * (`tests/session-engine-cache.spec.ts`). The one part that needs a component to
+ * render — the hook that subscribes a surface to the cache — lives in
+ * `./use-session-engine.ts`.
+ *
+ * The cache owns NO document-level side effect, deliberately. The chat
+ * turn-status row is painted through a document-level attribute
+ * (`./turn-status.ts`), so the only writer entitled to it is the session on
+ * screen — and this cache publishes for every session a surface has ever
+ * watched, the session the user just left included. Reflecting from
+ * `publish` therefore let a background session's (or a left session's late)
+ * answer take the attribute over from the session on screen, which painted ITS
+ * engine onto the row beside it — a session running pi drew Kimi's moon. The
+ * reflection is driven from `./use-session-engine.ts` instead: that hook is
+ * where a component knows which session it is the surface of, and the reflection
+ * it makes carries a focus guard. Here the cache answers one question only —
+ * what one session's engine is.
+ *
+ * One member of the framework's standard seat is still read from the slot props:
+ * the session-scope `sessionId`. The harness declares it by declaration-merging
+ * `SessionStandardProps` in `@deepseek-ai/dsh-client-ui-session/client`, and its
+ * published declarations elide the type-only imports that carry the merge — so a
+ * half compiled against the installed artifacts (this package's
+ * `tsconfig.build.json` pins `@deepseek-ai/*` to the artifact plane) never sees
+ * it. It is therefore restated structurally here, in the shape the harness
+ * declares (`packages/client/ui-session/src/client/index.ts`), and the
+ * components assert it off their slot props. The `useSessions` hook needs no
+ * such restatement any more: nothing here reads the session list.
+ *
+ * The Remote's client-side types are restated structurally for the same reason
+ * and one more: a third-party plugin cannot reach the main repository's
+ * generated `typert.remote-client.d.ts`, and it does not need to — the protocol
+ * has no schema registry, so a contribution is plain data (see
+ * `LOOP_ENGINE_REMOTE_CONTRIBUTION`).
+ *
+ * @module dsh-loop-engine/client/session-engine
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type LoopEngineId, type LoopEngineRefusalCode, type LoopEngineSelectResult, type SessionEngine, type SessionEngineReport } from '../agent-preset-ids.ts';
+import { type ReloadPage } from './reload.ts';
+/**
+ * The three-state engine answer, re-exported so the client half names one type.
+ * It is DEFINED in the zero-import shared module: the node half decides it
+ * (`src/engine-of-session.ts`) and this half only renders what it is told.
+ */
+export type { SessionEngine } from '../agent-preset-ids.ts';
+/**
+ * What one session's engine read answers: the engine it ACTUALLY runs, plus the
+ * engine a committed switch has recorded for it but not yet reached.
+ *
+ * Re-exported for the same reason as the three-state: the split between the two
+ * facts is decided on the host (`src/engine-of-session.ts`) and this half renders
+ * both without ever merging them — the pending engine belongs in a "not in force
+ * yet" marker, never in the place that names what the session runs.
+ */
+export type { SessionEngineReport } from '../agent-preset-ids.ts';
+/**
+ * The standard seat members this half reads off a session-scope slot.
+ *
+ * Only the identity: the engine itself is no longer read from a framework hook,
+ * it is asked of the host through this plugin's own Remote.
+ */
+export interface SessionSeat {
+    /**
+     * Current Session identity. Undefined only off a seat rendered without a
+     * session: the composer then picks the new-session default, and the header chip
+     * (which only ever renders with a session) shows nothing.
+     */
+    sessionId?: string;
+}
+/** Cordis service key AND wire namespace of the plugin's own Remote. */
+export declare const LOOP_ENGINE_REMOTE_NAMESPACE = "loopEngine";
+/** Reporting endpoint of the plugin's own Remote (mirrors `src/engine-remote.ts`). */
+export declare const LOOP_ENGINE_REMOTE_METHOD = "engine";
+/** Switching endpoint of the plugin's own Remote (mirrors `src/engine-remote.ts`). */
+export declare const LOOP_ENGINE_REMOTE_SELECT_METHOD = "select";
+/** One refused Remote call (harness: the error branch of `RemoteResult`). */
+export interface RemoteFailure {
+    /** The host's own framing of the refusal. */
+    readonly message: string;
+    /** The refusal's detail map; a `reason` entry carries the unframed cause. */
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/** What `remote.loopEngine.engine` resolves to (harness: `RemoteResult<SessionEngineReport>`). */
+export type SessionEngineResult = {
+    readonly ok: true;
+    readonly value: SessionEngineReport;
+} | {
+    readonly ok: false;
+    readonly error: RemoteFailure;
+};
+/** What `remote.loopEngine.select` resolves to (harness: `RemoteResult<LoopEngineSelectResult>`). */
+export type EngineSelectResult = {
+    readonly ok: true;
+    readonly value: LoopEngineSelectResult;
+} | {
+    readonly ok: false;
+    readonly error: RemoteFailure;
+};
+/** This plugin's own Remote namespace, as the browser half calls it. */
+export interface SessionEngineRemote {
+    /** Report the engine one session runs (and the recorded engine it is not running, if any). */
+    engine(request: {
+        readonly sessionId: string;
+    }): Promise<SessionEngineResult>;
+    /** Move one session to another engine, or answer why it was not moved. */
+    select(request: {
+        readonly sessionId: string;
+        readonly engine: LoopEngineId;
+    }): Promise<EngineSelectResult>;
+}
+/** Outcome of one per-session engine switch, ready to render. */
+export type SessionSwitchResult = {
+    readonly ok: true;
+    /**
+     * Present when the host made the switch land by RELEASING the session's
+     * agent — a change with the harness loop on either side of it. This page has
+     * already been reloaded (and the session remembered for the page that
+     * replaces it) by the time a caller sees this, so a surface renders it as
+     * "the switch is happening" rather than as a session that can be typed into.
+     */
+    readonly reload?: true;
+}
+/** This page cannot reach the plugin's own Remote at all. */
+ | {
+    readonly ok: false;
+    readonly kind: 'unavailable';
+}
+/**
+ * The host refused the switch. `code` says which refusal it was, for the
+ * surface to render in the user's language, and `reason` is the host's own
+ * sentence about this session — detail under that copy, or the whole message
+ * when the code is absent (an unknown code, a rejected CALL, a lost
+ * connection: none of those has a refusal code, and none of them may leave the
+ * surface with nothing to show).
+ */
+ | {
+    readonly ok: false;
+    readonly kind: 'refused';
+    readonly reason: string;
+    readonly code?: LoopEngineRefusalCode;
+};
+/** Move one session to another engine. */
+export type SessionEngineSwitcher = (sessionId: string, engine: LoopEngineId) => Promise<SessionSwitchResult>;
+/**
+ * Whether a pick on one session's engine can be committed at all — that is,
+ * whether the host has answered what that session runs.
+ *
+ * This is the composer's usability gate, and it is hostile to guessing on
+ * purpose. The reload judgement below is a statement about two engines, and with
+ * no answer there is nothing honest to state: an unknown session may reload in
+ * EITHER direction. Answering the question anyway would cost the user something
+ * either way — `true` raises a confirmation for a switch that may not reload
+ * (and the confirmation is the only thing keeping an UNEXPLAINED reload from
+ * looking like a glitch), while `false` commits a pick that reloads and takes
+ * this page's unsent draft with it. So the picker is simply not usable until the
+ * answer lands: the trigger is greyed out with its menu unopenable, and it keeps
+ * reading「读取中…」so the user can see what it is waiting for. The instant the
+ * answer arrives the control becomes usable, unchanged.
+ *
+ * It is a TYPE PREDICATE as well as the runtime gate, so "no pick is ever judged
+ * against an unknown engine" is enforced by the compiler: the composer narrows a
+ * session's report through this before it asks {@link switchNeedsReload}, whose
+ * parameter therefore cannot be undefined.
+ *
+ * A seat with NO session is not this function's business and never calls it: it
+ * writes the default for sessions created later, moves nothing, and reloads
+ * nothing, so there is no engine to wait for.
+ * @param report - the session's engine report, or undefined while the host has
+ * not answered yet (or cannot answer at all).
+ * @returns whether the engine is known — the one condition under which a pick on
+ * that session may be judged and sent.
+ */
+export declare function engineSwitchReady(report: SessionEngineReport | undefined): report is SessionEngineReport;
+/**
+ * Whether moving a session from `current` to `target` has to land through a page
+ * reload — the one thing a surface must ask the user about BEFORE it commits,
+ * because the reload is what takes this page's unsent draft and scroll position
+ * with it.
+ *
+ * The rule is the host's own split (`src/router-loop.ts` `move`): a move with the
+ * harness loop on EITHER side cannot be handed over in place — `AgentLoop` neither
+ * hands a live session over nor accepts one it did not create — so the session's
+ * agent is released, the session goes cold, and the page reloads to rebuild it on
+ * the recorded engine. Between two hosted engines nothing reloads: the agent is
+ * swapped in place and the conversation stays open. So the move reloads exactly
+ * when the two engines differ in being the in-process one.
+ *
+ * `current` is the engine the session ACTUALLY runs — the report's `engine`, never
+ * the engine its record names, which is why this takes a {@link SessionEngine} and
+ * not a bare id:
+ *
+ *  - a state that names an engine answers the rule above directly;
+ *  - `legacy` and `unset` name no engine, and both are built on the in-process
+ *    loop (`src/agent-preset-ids.ts` `hostedEngineOf` — the router falls back to
+ *    the harness loop for a preset this plugin does not own), so they are read as
+ *    the in-process side of the rule rather than as "unknown": picking any hosted
+ *    engine on such a session really does reload.
+ *
+ * There is deliberately NO third branch for "the host has not answered yet": that
+ * state never reaches here, because the composer gates every pick on
+ * {@link engineSwitchReady} first (the picker is disabled until the answer lands),
+ * and the parameter's non-optional type is what holds that down. A judgement made
+ * without an answer would be a guess in one direction or the other, which is
+ * exactly what the gate exists to avoid.
+ *
+ * It is a pure function of the two engines on purpose: the composer's confirmation
+ * is only as trustworthy as this judgement, and this way it is pinned by a test
+ * rather than by reading the component.
+ * @param current - the engine the session runs now, as the host reports it. Never
+ * unknown: callers hold a report that passed {@link engineSwitchReady}.
+ * @param target - the engine the user picked.
+ * @returns whether committing that pick releases the session's agent and reloads
+ * this page.
+ */
+export declare function switchNeedsReload(current: SessionEngine, target: LoopEngineId): boolean;
+/** A codec of one wire field (harness: `TypertCodec`, strict branch). */
+interface RemoteCodec {
+    readonly mode: 'strict';
+    /** Stable identity of the field's declared type, for diagnostics. */
+    readonly typeSymbol: string;
+    readonly schema: {
+        parse(value: unknown): unknown;
+    };
+}
+/** One ordered business parameter (harness: `InvocationParameterDescriptor`). */
+interface RemoteParameter {
+    readonly name: string;
+    /** Wire field this parameter occupies in `args`. */
+    readonly wire: string;
+    readonly source: 'json';
+    readonly codec: RemoteCodec;
+}
+/** One exported method (harness: `InvocationDescriptor`). */
+interface RemoteMethod {
+    readonly id: string;
+    readonly service: string;
+    readonly namespace: string;
+    readonly method: string;
+    readonly invocation: {
+        readonly kind: 'direct';
+    };
+    readonly parameters: readonly RemoteParameter[];
+    readonly result: RemoteCodec;
+}
+/** One package's exported methods (harness: `TypertRemoteContribution`). */
+export interface RemoteContribution {
+    readonly package: string;
+    readonly descriptors: readonly RemoteMethod[];
+}
+/** The Client Remote service, as much of it as this half calls (harness: `ClientRemote`). */
+export interface EngineRemoteHost {
+    /** Install one contribution's namespaces for the calling fiber. */
+    $mount(contribution: RemoteContribution): Promise<() => Promise<void>>;
+}
+/** The plugin's npm package name, as the contribution identifies itself. */
+export declare const LOOP_ENGINE_PACKAGE = "dsh-loop-engine";
+/** The plugin's own Remote, declared for the Gateway's client mount. */
+export declare const LOOP_ENGINE_REMOTE_CONTRIBUTION: RemoteContribution;
+/**
+ * What one session's engine is, cached per session.
+ *
+ * Every read goes to the host's authoritative answer and is cached by session id
+ * so the chip and the composer in the same header cannot disagree. Until the
+ * first answer arrives a session has NO engine here: {@link read} returns
+ * undefined, and the surfaces render nothing (chip) or a neutral loading state
+ * (composer) rather than a guess — a default or a list hint would be exactly the
+ * misreport this class exists to end.
+ *
+ * What is cached is the whole {@link SessionEngineReport}, the recorded engine
+ * that differs from the live one included, because the three surfaces read
+ * different halves of it: the chip, the composer's label, and the chat
+ * turn-status row all name the engine the session RUNS, and only the first two
+ * also carry the "recorded, not in force" marker. Merging the two here would
+ * make that distinction unavailable downstream; leaving the report intact lets
+ * each surface take the half it renders.
+ *
+ * A cached answer is never treated as final for the page's lifetime: a session
+ * the user comes back to is re-read when its surfaces appear again
+ * ({@link watch} → {@link refresh}). Coming back does not move the session — a
+ * switch is performed on the host, between hosted engines it swaps the agent in
+ * place, and the direction that has to release the session reloads this very
+ * page (`./reload.ts`) — but the answer this page holds is still only one this
+ * page took earlier: another window, a hot swap performed elsewhere, or a plugin
+ * reload can have moved the session since. The answer a surface holds is
+ * therefore correct for as long as that surface is on screen, and refreshed at
+ * every re-mount — not only when a switch this page performed invalidated it
+ * ({@link invalidate}).
+ *
+ * Its answer is also what the chat turn-status row draws (the third place a
+ * session's engine is shown), but through the surfaces rather than through this
+ * class: the row follows the session on screen because the hook both surfaces
+ * share reflects that session's answer with a focus guard — the same authority
+ * the chip and the composer read, where the settings default it used to follow
+ * was not. Nothing here writes to the document; see `./turn-status.ts` and
+ * `./use-session-engine.ts`.
+ */
+export declare class SessionEngineCache {
+    private readonly engines;
+    private readonly watchers;
+    private readonly reading;
+    /**
+     * Monotonic read generation per session. A read started before an
+     * invalidation describes the session as it was BEFORE the switch, so however
+     * late it settles it must not publish — publishing it would put the old engine
+     * back on screen, which is the very misreport this cache exists to prevent.
+     */
+    private readonly generations;
+    private remote;
+    private disposed;
+    /**
+     * Attach the mounted Remote namespace. Values asked for before the mount
+     * settled are re-read, so a surface that mounted first is not left loading.
+     * @param remote - the namespace, or undefined when the mount failed.
+     */
+    attach(remote: SessionEngineRemote | undefined): void;
+    /**
+     * The engine report cached for one session, or undefined while the first
+     * answer is still in flight (or when the host could not answer at all).
+     * @param sessionId - the session whose engine is asked for.
+     * @returns the authoritative report, cached by session id.
+     */
+    read(sessionId: string): SessionEngineReport | undefined;
+    /**
+     * Follow one session's engine, re-reading it whenever a session's surfaces
+     * appear again.
+     *
+     * A watch is a surface appearing for this session, and that is the moment the
+     * cached answer can be stale in a way nothing else reports: a session whose
+     * surfaces all went away and came back — the page switched to another session
+     * and back — must not render what the page cached before. A re-mount is not
+     * what moves a session's engine (a switch is performed on the host, and either
+     * swaps the agent in place or releases the session and reloads this page), but
+     * the page's answer is old by then, and a surface that rendered it as current
+     * would be the one lying about what runs.
+     *
+     * Only the FIRST watcher of a session triggers the re-read, which is what
+     * makes this "the session's surfaces appeared" rather than "a component
+     * rendered": the chip and the composer are two watchers of one session, and
+     * the second joins the read the first one started instead of sending its own.
+     * While a session keeps its surfaces, nothing here asks again — the answer only
+     * changes through {@link invalidate} (a committed switch) or a later re-mount.
+     * @param sessionId - the session to follow.
+     * @param listener - called whenever that session's cached state changes.
+     * @returns the unsubscribe.
+     */
+    watch(sessionId: string, listener: () => void): () => void;
+    /**
+     * Ask the host for one session's engine report again, superseding nothing.
+     *
+     * This is the way a surface that has just been rendered asks "is what this page
+     * cached still what runs?" — the answer that can go stale without anyone
+     * invalidating it, because the page is not the only thing that can move a
+     * session (another window, a hot swap elsewhere, a plugin reload).
+     * A read already in flight for that session is joined rather than replaced (it
+     * was started no earlier than this call and describes the same moment), and the
+     * cached answer is kept until the new one lands, so a re-read never blinks the
+     * chip back to "reading". Use {@link invalidate} instead for an answer that is
+     * known to be WRONG.
+     * @param sessionId - the session whose answer should be re-read.
+     */
+    refresh(sessionId: string): void;
+    /**
+     * Forget one session's cached engine and ask the host again.
+     *
+     * A successful engine switch changes what the host answers for that session,
+     * so the picker MUST come through here: without it the composer would keep
+     * showing the engine the session no longer runs. Any read already in flight
+     * for that session is superseded and can no longer publish.
+     * @param sessionId - the session whose answer is now stale.
+     */
+    invalidate(sessionId: string): void;
+    /** Drop every cached answer and notification (plugin unload). */
+    dispose(): void;
+    /**
+     * Ask unless the session is already answered, being read, or unanswerable.
+     *
+     * For the paths that need an answer and have none: the plugin's mount settling
+     * (a surface asked before the Remote existed), a session whose cached answer
+     * was just dropped — and never a re-read of an answer this page already holds,
+     * which is {@link refresh}'s job and only a freshly rendered surface may ask
+     * for.
+     */
+    private readIfUnknown;
+    /**
+     * Start one read for a session, unless there is nothing to read it with.
+     * @param sessionId - the session to read.
+     */
+    private start;
+    /**
+     * One read, quiet on failure: a session the host cannot answer for stays
+     * unknown, and the surfaces keep their neutral state instead of claiming an
+     * engine. A refusal is not cached as an answer, so the next watch re-asks.
+     * @param remote - the mounted namespace.
+     * @param sessionId - the session asked about.
+     * @param generation - the read generation this answer belongs to.
+     */
+    private ask;
+    /**
+     * Notify one session's watchers.
+     *
+     * Nothing is painted here. The session's engine shows up in the chat
+     * turn-status row too, but that row hangs off a DOCUMENT-level attribute, whose
+     * only entitled owner is the session on screen — and a publish says nothing
+     * about what is on screen (this is called for every session a surface has ever
+     * watched, and for a session the user has already left, when its late answer
+     * lands). So painting here let a background session take the attribute over
+     * from the session on screen. The surfaces reflect instead, with the focus
+     * guard in `./turn-status.ts`; this is the notification the chip and the
+     * composer wake up on.
+     */
+    private publish;
+}
+/**
+ * Mount this plugin's own engine Remote and return the cache the session
+ * surfaces render from.
+ *
+ * `remote` is taken lazily rather than declared in the client half's `inject`:
+ * the settings page must keep working on a page that composes no Gateway, and
+ * the two session surfaces degrade to "engine not recorded" — never to a guess.
+ * @param ctx - the client root context.
+ * @returns the cache both session surfaces and the switcher share.
+ */
+export declare function createSessionEngineCache(ctx: ClientContext): SessionEngineCache;
+/**
+ * Build the per-session switch over this plugin's own Remote.
+ *
+ * Every refusal is reported rather than thrown: the host's own reason when it
+ * refused (the session is not open, it is mid-turn, it belongs to subagent
+ * routing, or the engine record could not be written), and this page's own words
+ * when the namespace is not reachable. A switch that DID land drops the cached
+ * answer, because the host's read for that session just changed.
+ *
+ * A switch the host had to make by RELEASING the session's agent is finished
+ * here rather than reported: the page is reloaded — the only action that clears
+ * the client state a `session/disposed` leaves behind — and the session is
+ * stashed for the page that replaces it, so the reload lands back on it
+ * (`./reload.ts` explains why each half is necessary). That is why this function
+ * owns the reload instead of leaving it to a component: it is the one place that
+ * knows the host released the agent, and it keeps the sequence (invalidate →
+ * stash → reload) in one testable step.
+ * @param ctx - the client context carrying the Remote namespace.
+ * @param onSwitched - called with the session id once the host accepted the
+ *   switch, so the caller can drop the cached engine it just changed.
+ * @param page - the page to reload and to stash the return in.
+ * @returns the switch the composer's picker commits through.
+ */
+export declare function sessionEngineSwitcher(ctx: ClientContext, onSwitched?: (sessionId: string) => void, page?: ReloadPage): SessionEngineSwitcher;
+//# sourceMappingURL=session-engine.d.ts.map

package/lib/types/client/store.d.ts

@@ -5,7 +5,7 @@
  */
 import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
-import type { LoopEngineId } from '../settings.ts';
+import type { LoopEngineId } from '../agent-preset-ids.ts';
 /** State rendered by the loop engine section. */
 export interface LoopEngineState {
     status: 'loading' | 'ready' | 'unavailable' | 'saving';

package/lib/types/client/turn-status.d.ts

@@ -6,8 +6,46 @@
  * namespace (a second `locale.register` for the same namespace throws), so a
  * plugin cannot change the text. What it CAN do is restyle the element, and
  * that is all this module does — it paints an engine-specific glyph and color
- * onto the row while a hosted engine is selected, and leaves the stock look
- * alone otherwise.
+ * onto the row while the session on screen runs a hosted engine, and leaves the
+ * stock look alone otherwise.
+ *
+ * WHICH engine it paints is the SESSION ON SCREEN's, not the settings default.
+ * {@link reflectTurnStatusEngine} is driven from the per-session engine cache
+ * (`./session-engine.ts`) — the same authoritative answer the header chip and
+ * the composer render from, the plugin's own Remote read off the session's
+ * durable log — and it is driven by the ONE hook those two surfaces share
+ * (`./use-session-engine.ts`). So this row cannot disagree with the two surfaces
+ * beside it; while it was keyed off the settings store it did, and painted
+ * Claude Code's glyph onto every session's row whenever claude-code was the
+ * default, a session running pi included.
+ *
+ * The reflection's SUBJECT is still a document-level attribute rather than the
+ * row's own element: the sheet has to reach a class the harness hashes
+ * (`[class$="_turnStatus"]`), which takes an attribute selector on an ancestor,
+ * and the row offers no session-scoped hook for a plugin to hang it on. A
+ * document-level attribute has exactly ONE owner at a time, though — and on this
+ * page the WRITERS outnumber the reader: the chip and the composer of every
+ * session that has been rendered carry an answer, the session the user has just
+ * left included, and the cache publishes a session's answer regardless of what is
+ * on screen. So "whoever reflected last" is not "the session on screen", and an
+ * implementation that read it as one shipped the bug this guard ends: a
+ * background session's answer — or the late answer of the session the user just
+ * left — painted ITS engine onto the row of the session on screen, and a session
+ * running pi showed Kimi's moon.
+ *
+ * The owner is therefore DECLARED, not inferred: a reflection names the session
+ * it speaks for and writes only while that session is the row's focus
+ * ({@link focusTurnStatusSession}); a reflection whose subject is not the focused
+ * session is a NO-OP, so only the session on screen can paint and only it can
+ * un-paint. The chip and the composer of one session reflect the same value (the
+ * write is idempotent); the focus is withdrawn by
+ * {@link blurTurnStatusSession}, which acts only while the focus is still the
+ * departing session's (React runs a departing component's cleanup in no
+ * guaranteed order against an arriving one's, so an unconditional withdrawal
+ * would un-focus the session that just took over); and the attribute itself is
+ * never withdrawn on unmount: the sibling surface of the same session still
+ * paints by it, and a leftover attribute is inert on a page whose turn-status row
+ * is not rendered.
  *
  * Three facts about the harness markup make that safe and specific:
  *   - the row carries exactly one class whose `[hash]_turnStatus` suffix is
@@ -28,16 +66,80 @@
  * @module dsh-loop-engine/client/turn-status
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
-import type { LoopEngineState } from './store.ts';
+import type { LoopEngineId } from '../agent-preset-ids.ts';
+/**
+ * Reflect the engine of the session ON SCREEN; `undefined` restores the stock
+ * row.
+ *
+ * The caller names the session it speaks for, and that is the row's SUBJECT: a
+ * reflection paints its session's engine only while that session is the focused
+ * one ({@link focusTurnStatusSession}), and is a NO-OP otherwise — the whole
+ * guard, and the reason the attribute can no longer be taken over by a session
+ * the user is not looking at. The subject is an explicit argument rather than
+ * ambient state, so a caller cannot reflect without saying whose engine it is,
+ * and cannot say "whoever, I don't know".
+ *
+ * `in-process` is the harness's own row, and `undefined` is every answer that
+ * names no engine at all: a session the host reports as `legacy` (it ran a
+ * hosted engine, the id never said which) or `unset`, a session whose first
+ * answer has not landed yet, and an answer dropped in preparation for a re-read.
+ * None of them paints — naming an engine for an unknown one is the misreport
+ * this module was fixed for — so each clears the attribute. The clear is as
+ * authoritative as the paint: a session that takes the focus with no answer yet
+ * takes the previous session's paint off with it.
+ *
+ * The write is idempotent and never a withdrawal: the chip and the composer of
+ * one session both come through here with the same value, and unmounting never
+ * clears the attribute, because the sibling surface of the same session is still
+ * on screen painting through it.
+ *
+ * The NO-OP covers the late reflection as well — the one from the session the
+ * user has just left, whose own answer landing after the switch used to paint
+ * over the session that replaced it.
+ * @param sessionId - the session this reflection speaks for, or undefined for a
+ *   page with no session at all (the new-session page, which has no turn-status
+ *   row): such a page has nothing to say about the row, so nothing is written and
+ *   nothing is withdrawn — it leaves the row it found alone.
+ * @param engine - the engine that session runs, when it is known.
+ */
+export declare function reflectTurnStatusEngine(sessionId: string | undefined, engine: LoopEngineId | undefined): void;
+/**
+ * Declare which session's surfaces are on screen — the row's one subject.
+ *
+ * Only the focused session may paint ({@link reflectTurnStatusEngine}), which is
+ * what keeps the row on the session the user is looking at: the alternative,
+ * "whoever writes last owns the row", was the bug this guard ends, because the
+ * chip and the composer of EVERY session that has been rendered write here, and
+ * a session's answer can land after the user has left it.
+ *
+ * The caller is the component that renders that session: only a component knows
+ * which session is the one on screen, and the hook both of that session's
+ * surfaces share (`./use-session-engine.ts`) is the only place that declares it.
+ * @param sessionId - the session whose surfaces are now on screen.
+ */
+export declare function focusTurnStatusSession(sessionId: string): void;
+/**
+ * Withdraw the focus — but only while it is still this session's.
+ *
+ * The guard is the point: React offers no ordering guarantee between a departing
+ * component's cleanup and an arriving one's, so an unconditional withdrawal would
+ * let the session the user has just left un-focus the session that replaced it
+ * and silence the row. A session that is no longer the focus has nothing to
+ * withdraw; unmounting also never clears the attribute itself, which the sibling
+ * surface of the same session (and, for a session that is still on screen, the
+ * next focus) still paints by.
+ * @param sessionId - the session whose surface is going away.
+ */
+export declare function blurTurnStatusSession(sessionId: string): void;
 /**
- * Install the per-engine turn-status styling for the lifetime of `ctx`.
+ * Install the per-engine turn-status stylesheet for the lifetime of `ctx`.
  *
- * Keyed off the shared controller store, so it follows a live engine switch
- * exactly as the settings section and header chip do; the store is read rather
- * than the settings scope so all three surfaces cannot disagree.
+ * This is the sheet and nothing else: which engine it selects is written by
+ * {@link reflectTurnStatusEngine}, driven from the session on screen's own
+ * authoritative answer (`./session-engine.ts`), through the hook the chip and
+ * the composer share (`./use-session-engine.ts`) — not from the settings
+ * default.
  * @param ctx - the client root context.
- * @param store - the loop-engine controller's snapshot source.
  */
-export declare function installTurnStatusStyles(ctx: ClientContext, store: SnapshotStore<LoopEngineState>): void;
+export declare function installTurnStatusStyles(ctx: ClientContext): void;
 //# sourceMappingURL=turn-status.d.ts.map