@deepseek-harness-tui/dsh-tui 0.11.2 → 0.13.0

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

@@ -5,11 +5,13 @@ import { createCommandCompletions } from './channel/command-completions.js';
 import { createLocalActions } from './channel/local-actions.js';
 import { createDetachedHandleFactory } from './channel/lifetime-resources.js';
 import { createContextBookkeeping } from './channel/context-bookkeeping.js';
+import { resolveContextOccupancy } from './context-occupancy.js';
 import { createChannelActionMethods, createChannelActionReadiness } from './channel/action-readiness.js';
 import { createBindingEvents } from './channel/binding-events.js';
 import { createInitialChannelView } from './channel/state.js';
 import { createChannelProjection } from './channel/projection.js';
 import { createManualCompaction } from './channel/compaction.js';
+import { agentCapabilityEvidence, annotateCommandCapabilities, resolveAgentCapabilities } from './channel/capabilities.js';
 import { createSessionAdoption } from './channel/session-adoption.js';
 import { createRewindPromptAction } from './channel/session-actions.js';
 import { createForkSessionAction } from './channel/session-fork.js';
@@ -32,6 +34,7 @@ import { createSkillCatalog } from './channel/skill-catalog.js';
 import { createBackgroundCurrentAction } from './channel/background-action.js';
 import { createSubagentProjection } from './channel/subagent-projection.js';
 import { createChannelNotifications } from './channel/notifications.js';
+import { createAttachedContextRegistry } from './channel/attached-context.js';
 import { createSelectionAttachments } from './channel/ide-selection.js';
 import { IdeChannel, ideLockDir } from './ide-channel.js';
 import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
@@ -162,6 +165,7 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
     const jobControl = jobProjection.control;
     const attachJobs = jobProjection.attach;
     const resetJobProjection = jobProjection.reset;
+    const reanchorJobProjection = jobProjection.reanchor;
     // The DSH slash-command registry (optional service): /plan, /goal and
     // friends register here; the TUI merges their descriptors into the slash
     // menu and dispatches through `execute` (which logs the paired
@@ -275,8 +279,13 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
         void ideChannel.rebind(state.cwd).catch(() => { });
     };
     const selectionAttachments = createSelectionAttachments();
+    // "Send to Chat" (side-panel §6.7): staged panel contexts are a session-scoped
+    // projection like the selection above — the registry writes through the live
+    // state (so the shared `session-projection reset` clears them with everything
+    // else) and the submit path takes them off in one step.
+    const contextRegistry = createAttachedContextRegistry(() => state, () => state.emit());
     const composer = createComposerImages(ctx, owner, { generation: () => state.agentBindingGeneration });
-    const inputDelivery = createInputDelivery(ctx, owner, binding, () => state, (...args) => notify(...args), trackPending, untrackPending, composer, () => currentSelection, (messageId, info) => selectionAttachments.remember(messageId, info));
+    const inputDelivery = createInputDelivery(ctx, owner, binding, () => state, (...args) => notify(...args), trackPending, untrackPending, composer, () => currentSelection, (messageId, info) => selectionAttachments.remember(messageId, info), () => contextRegistry.consume());
     const { dispatchUserText, deliverUserText, retireAttachment, withDecisionPending, clearStagedImages } = inputDelivery;
     /**
      * The `tui/session-switch` decision event (pi's `session_before_switch`),
@@ -390,6 +399,13 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
         return actionReadiness.getReadyActions();
     };
     const actionMethods = createChannelActionMethods(getReadyActions);
+    // Capability facts for the bound agent (channel/capabilities.ts). Reads are
+    // service lookups, so both consumers may call it freely: the public
+    // `capabilities()` accessor and the command-list annotation below.
+    const capabilitiesOf = () => resolveAgentCapabilities(agentCapabilityEvidence(ctx, binding.agent));
+    // Official occupancy source (absent in compositions without the token meter):
+    // `read` is a cached lookup, so the accessor on the state below stays cheap.
+    const contextPressure = options.contextPressure;
     const state = {
         ...createInputActions(() => state, () => binding.agent, owner, inputConvergence, composer, (text, placement, images) => dispatchUserText(text, placement, images), (command, includeInContext) => getReadyActions().runLocalCommand(command, includeInContext)),
         subscribe: emitter.subscribe,
@@ -413,7 +429,30 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
             mode: sessionModes[0],
             cwdDescription: workspaceService.describe(options.cwd).description ?? options.cwd,
         }),
-        commandList: LOCAL_COMMANDS,
+        // Deprecated pre-rename alias of `minimalUi`. An accessor is required here
+        // (a field set in createInitialChannelView would be copied by the spread
+        // into a stale data property). Read-only on purpose: the only supported
+        // write path is `setMinimalUi()` / its `setMinimal()` alias, and the
+        // frozen `ChannelUi` view third-party scenes receive exposes it read-only
+        // anyway.
+        get minimal() {
+            return state.minimalUi;
+        },
+        /**
+         * Context occupancy is DERIVED here, not stored: it combines the cached
+         * host projection value (a map lookup) with this channel's own fallback
+         * sample and capacity. An accessor is what keeps "one source of truth"
+         * true without republishing a derived value from every mutation site that
+         * can move the window or the sample (replay, resume, model switch, reset).
+         */
+        get contextOccupancy() {
+            return resolveContextOccupancy(contextPressure?.read(state.sessionId), state.lastUsage, state.contextWindow);
+        },
+        // Annotated from the start: Help and `/` completion read `commandList`
+        // before the first skill-catalog refresh publishes a new one, and a command
+        // whose capability is missing must never look usable in that window.
+        commandList: annotateCommandCapabilities(LOCAL_COMMANDS, capabilitiesOf()),
+        capabilities: capabilitiesOf,
         ...actionMethods,
         subagentControl,
         jobControl,
@@ -424,6 +463,11 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
         discardStagedImage: composer.discardStagedImage,
         stagedImage: composer.stagedImage,
         stagedImageLimits: composer.stagedImageLimits,
+        // "Send to Chat" projection + actions (see `contextRegistry` above; its
+        // methods close over the registry's own state, so they carry no `this`).
+        attachedContexts: [],
+        attachContext: contextRegistry.attach,
+        detachContext: contextRegistry.detach,
         /**
          * The `tui/rewind-prompt` decision event (pi's `session_before_fork`):
          * fired when the rewind picker confirms a message, before any fork
@@ -493,6 +537,18 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
     // callback. The renderer lease binds its external authority later, but this
     // owner already makes teardown and construction failure fail closed.
     registerChannelOwner(state, owner);
+    // The projection's change feed is the only thing that can move occupancy
+    // between session events (a compaction rewriting the surface, the prompt
+    // growing before the next request); republish so the footer, the status
+    // commands and the warning read the fresh value immediately. The store is
+    // host-wide, so the emit is unconditional — the accessor already ignores
+    // another session's value.
+    if (contextPressure !== undefined) {
+        owner.own(contextPressure.subscribe(() => {
+            if (owner.current())
+                state.emit();
+        }));
+    }
     // Agent-view is activated after the complete state/action surface exists:
     // no roster callback or persistence continuation can observe an unbound UI.
     agentView = createAgentViewProjection(ctx, {
@@ -528,7 +584,13 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
         commandService,
         agent: () => binding.agent,
         cwd: () => state.cwd,
-        setCommands(commands) { state.commandList = commands; state.emit(); },
+        setCommands(commands) {
+            // Annotate before publishing: Help and `/` completion both read
+            // `commandList`, so a command whose capability is missing says so
+            // instead of looking usable and failing on use.
+            state.commandList = annotateCommandCapabilities(commands, capabilitiesOf());
+            state.emit();
+        },
         commandDescriptions: name => commandTrees?.descriptions(name),
         // Attached-context pass-through (T03 consumes the third parameter in the
         // fallback branch): the skill catalog never loses the FIFO/decision fence.
@@ -705,6 +767,7 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
         binding,
         state,
         seedActivity: options.seedActivity,
+        seedContextOccupancy: options.seedContextOccupancy,
         inputConvergence,
         selection,
         modelActions,
@@ -715,7 +778,12 @@ function createChannelWithOwner(ctx, initialAgent, options, owner) {
         messageObserver,
         retireAttachment,
     });
-    const bindAgent = bindingEvents.bind;
+    const rawBindAgent = bindingEvents.bind;
+    /** Bind the new agent, then re-anchor the job projection: its event
+     *  subscription is deliberately owner-agnostic, so this is what makes the
+     *  /jobs roster follow a session switch immediately instead of waiting for
+     *  the new session's first job event. */
+    const bindAgent = () => { rawBindAgent(); reanchorJobProjection(); };
     const sessionAdoption = createSessionAdoption(state, {
         binding,
         rowIds,

package/lib/types/dsh-adapter/context-occupancy.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Official context occupancy for the footer, the status commands and the
+ * context-low warning.
+ *
+ * Occupancy answers "how full is the window", which is NOT the question the
+ * provider usage of the last settled `assistant/message` answers. That sample
+ * has two blind spots this module removes:
+ *
+ * 1. **It is a sample of a *past* request.** A rejected/overflowed request
+ *    writes no `assistant/message`, so the sample stays small exactly when the
+ *    provider says the prompt is too big.
+ * 2. **It cannot see a compaction.** A checkpoint replaces the surface without
+ *    reporting usage of its own.
+ *
+ * DSH's token meter already projects both away: `contextPressure.projectedTokens`
+ * is the provider-anchored sample plus the signed surface movement since it was
+ * taken, i.e. the occupancy of the NEXT request. The Web UI reads that value
+ * through `ui-conversation`'s `contextOccupancy()`; this module reads the same
+ * projection through the same legal seam `activity-store.ts` uses
+ * (`ctx.inject(['sessionProjections'])` + the structural registry duck type +
+ * a cleanup on the injected fiber).
+ *
+ * Two properties shape the transport here:
+ *
+ * 1. **The change feed carries the whole value.** `onChanged` hands one unit's
+ *    schema-validated wire view (`session-projection/index.d.ts`), so this
+ *    module never folds history to stay current — only the session BIND reads
+ *    one snapshot, because a value that has not changed since it was published
+ *    never arrives again and a resumed session would otherwise show nothing.
+ * 2. **Absence is normal.** A bare `cordis.yml` composition has no dsh-base
+ *    bundle and therefore no token meter; the projection key is simply not
+ *    registered. The store stays empty and the channel falls back to the
+ *    last-request sample it has always shown (see `resolveContextOccupancy`).
+ * @module dsh-tui/dsh-adapter/context-occupancy
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContextOccupancy } from '../adapter/ports/channel-view.js';
+import type { ProjectionRegistryLike } from './activity-store.js';
+/** The projection key the host token meter publishes. */
+export declare const CONTEXT_PRESSURE_PROJECTION_KEY = "contextPressure";
+/**
+ * The official `contextPressure` wire value.
+ *
+ * Structural copy of `@deepseek-ai/dsh-token-meter`'s `ContextPressureProjection`:
+ * the value is host data, so this app declares the shape it reads instead of
+ * importing the meter (the same discipline `activity-store.ts` applies to
+ * `workingActivity`).
+ */
+export interface ContextPressureView {
+    /** Provider-reported prompt size (uncached input + cache reads/writes) of the newest request. */
+    readonly pressureTokens?: number;
+    /** What the NEXT request's prompt would cost: {@link pressureTokens} plus the surface's movement since. */
+    readonly projectedTokens?: number;
+    /** Newest recorded route capacity, when an adapter advertised one. */
+    readonly contextWindow?: number;
+}
+/**
+ * The reader the channel gets: a cached lookup plus a change feed.
+ *
+ * Reading is a map hit (never a fold), so a render may call it freely; the
+ * subscription is what lets the channel republish when the projection moves
+ * between session events (compaction, surface growth).
+ */
+export interface ContextPressureSource {
+    read(sessionId: string): ContextPressureView | undefined;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Narrow one projection value: anything that is not a context-pressure view is
+ * dropped rather than rendered half-formed.
+ *
+ * A well-formed value is passed THROUGH (not copied), the same discipline
+ * `activity-store.ts` applies: the host reuses the wire object while its state
+ * is unchanged, so identity is the store's change test, and a copy would make
+ * every read look like a change.
+ * @param value - Raw projection value.
+ * @returns the value as a context-pressure view, or `undefined`.
+ */
+export declare function asContextPressureView(value: unknown): ContextPressureView | undefined;
+/**
+ * The official numerator: `projectedTokens ?? pressureTokens`.
+ *
+ * This is the precedence `ui-conversation/src/client/context-occupancy.ts`
+ * uses. `projectedTokens` is preferred because it is the only field that
+ * answers for the next request; `pressureTokens` is the bare sample and is all
+ * a session whose surface total is unknown can offer.
+ * @param view - The projection value.
+ * @returns the occupancy numerator, or `undefined` before any provider sample.
+ */
+export declare function contextPressureUsedTokens(view: ContextPressureView): number | undefined;
+/**
+ * Resolve the ONE occupancy reading the footer, the segmented bar, the working
+ * line's pressure prefix, the status commands and the context-low warning share.
+ *
+ * DIVERGENCE FROM THE OFFICIAL RENDERER (deliberate, see the PR body): the Web
+ * UI renders nothing when the projection carries neither pressure nor a window.
+ * The TUI keeps its pre-projection sample readout instead, so a bare
+ * `cordis.yml` composition (no dsh-base bundle ⇒ no token meter) does not
+ * silently lose a number it has always shown; {@link ContextOccupancy.source}
+ * names which path answered. A composition WITH a meter — every normal
+ * deployment, where the base bundle mounts token-meter on the host plane —
+ * takes the projection branch as soon as a request reports usage, and the
+ * fallback becomes unreachable.
+ * @param projected - Cached `contextPressure` value, `undefined` without a meter.
+ * @param sample - Last settled request's billed usage (the fallback numerator).
+ * @param requestWindow - `request/context` capacity (the fallback denominator).
+ * @returns the reading, or `undefined` when neither path knows anything.
+ */
+export declare function resolveContextOccupancy(projected: ContextPressureView | undefined, sample: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+} | undefined, requestWindow: number | undefined): ContextOccupancy | undefined;
+/**
+ * The latest `contextPressure` value for the session on screen.
+ *
+ * Effectively single-current, mirroring {@link ActivityStore}: binding a
+ * session names the one the UI shows, and every other id is dropped — the
+ * projection feed is host-wide, and a background session must not overwrite the
+ * footer of the session on screen.
+ *
+ * The store holds VALUES, never sessions to re-read: the feed delivers the
+ * whole value, so there is nothing to poll. Only {@link seed} reads a snapshot,
+ * and only because a resumed session's value may not have changed (and
+ * therefore never been published) since it was last folded.
+ */
+export declare class ContextOccupancyStore implements ContextPressureSource {
+    private readonly values;
+    private readonly listeners;
+    /** The session the UI is showing (the last {@link seed}); the only id kept. */
+    private currentId;
+    /** Session object behind {@link currentId}, so a late registry can still seed. */
+    private currentSession;
+    /** Host registry, remembered so a bind can read a baseline on demand. */
+    private registry;
+    /** Read failures are reported once: a broken registry must not spam the log. */
+    private warned;
+    private readonly warn;
+    constructor(warn?: (message: string) => void);
+    /**
+     * Remember the host registry. A registry that arrives after the session bound
+     * is immediately used to read the baseline {@link seed} could not: the unit
+     * and its registry are mounted by other plugins, so the order is not ours.
+     * @param registry - The host projection registry.
+     */
+    attachRegistry(registry: ProjectionRegistryLike): void;
+    /**
+     * Bind one session and read its current projection value once.
+     *
+     * The bind also defines the session on screen: every other id is pruned, so a
+     * later background event can no longer fill this store.
+     * @param session - Session being bound.
+     */
+    seed(session: unknown): void;
+    /**
+     * Record one value from the projection change feed.
+     * @param sessionId - Session the value belongs to.
+     * @param value - The published wire value.
+     */
+    update(sessionId: string, value: unknown): void;
+    /** The current value for one session, stable between updates. */
+    read(sessionId: string): ContextPressureView | undefined;
+    /** Subscribe to value changes; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Report a failed registry read once. The sink is the composition root's
+     * logger — this module stays free of cordis types.
+     * @param error - What the failed read threw.
+     */
+    noteReadFailure(error: unknown): void;
+    /** Store one already-narrowed value for the current session and emit on change. */
+    private remember;
+    /** Drop every id that is not the current one; emit when a value went. */
+    private pruneToCurrent;
+    private emit;
+}
+/**
+ * Wire one store to the host's projection registry.
+ *
+ * Registration is deferred through `inject` because the plugin that *publishes*
+ * the unit is mounted alongside this one: the registry may not exist yet, and
+ * the unit may not be registered until later still. Both absences are normal —
+ * a composition without the token meter simply never fills the store, and the
+ * channel falls back to its own sample.
+ *
+ * The feed is event-driven and carries the whole value, so a change costs one
+ * narrow + one map write. A long resumed session (thousands of replayed events)
+ * therefore pays O(changes of this unit) and never a per-event fold; rendering
+ * pays a map lookup, never a `snapshot()`.
+ * @param ctx - Host context of the composition root.
+ * @param store - Store to fill.
+ */
+export declare function attachContextPressureProjection(ctx: Context, store: ContextOccupancyStore): void;
+/**
+ * Create the composition root's occupancy store and wire it to the host.
+ *
+ * Unlike the activity store there is no config gate: occupancy feeds the
+ * footer's ctx field, the segmented bar and the context-low warning, so hiding
+ * one surface must not stop the others from being correct.
+ * @param ctx - Host context of the composition root.
+ * @returns the store the channel reads from.
+ */
+export declare function createContextOccupancyStore(ctx: Context): ContextOccupancyStore;
+//# sourceMappingURL=context-occupancy.d.ts.map

package/lib/types/dsh-adapter/context-occupancy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-occupancy.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/context-occupancy.ts"],"names":[],"mappings":"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"}

package/lib/types/dsh-adapter/context-occupancy.js

@@ -0,0 +1,299 @@
+/**
+ * Official context occupancy for the footer, the status commands and the
+ * context-low warning.
+ *
+ * Occupancy answers "how full is the window", which is NOT the question the
+ * provider usage of the last settled `assistant/message` answers. That sample
+ * has two blind spots this module removes:
+ *
+ * 1. **It is a sample of a *past* request.** A rejected/overflowed request
+ *    writes no `assistant/message`, so the sample stays small exactly when the
+ *    provider says the prompt is too big.
+ * 2. **It cannot see a compaction.** A checkpoint replaces the surface without
+ *    reporting usage of its own.
+ *
+ * DSH's token meter already projects both away: `contextPressure.projectedTokens`
+ * is the provider-anchored sample plus the signed surface movement since it was
+ * taken, i.e. the occupancy of the NEXT request. The Web UI reads that value
+ * through `ui-conversation`'s `contextOccupancy()`; this module reads the same
+ * projection through the same legal seam `activity-store.ts` uses
+ * (`ctx.inject(['sessionProjections'])` + the structural registry duck type +
+ * a cleanup on the injected fiber).
+ *
+ * Two properties shape the transport here:
+ *
+ * 1. **The change feed carries the whole value.** `onChanged` hands one unit's
+ *    schema-validated wire view (`session-projection/index.d.ts`), so this
+ *    module never folds history to stay current — only the session BIND reads
+ *    one snapshot, because a value that has not changed since it was published
+ *    never arrives again and a resumed session would otherwise show nothing.
+ * 2. **Absence is normal.** A bare `cordis.yml` composition has no dsh-base
+ *    bundle and therefore no token meter; the projection key is simply not
+ *    registered. The store stays empty and the channel falls back to the
+ *    last-request sample it has always shown (see `resolveContextOccupancy`).
+ * @module dsh-tui/dsh-adapter/context-occupancy
+ */
+/** The projection key the host token meter publishes. */
+export const CONTEXT_PRESSURE_PROJECTION_KEY = 'contextPressure';
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Narrow one projection value: anything that is not a context-pressure view is
+ * dropped rather than rendered half-formed.
+ *
+ * A well-formed value is passed THROUGH (not copied), the same discipline
+ * `activity-store.ts` applies: the host reuses the wire object while its state
+ * is unchanged, so identity is the store's change test, and a copy would make
+ * every read look like a change.
+ * @param value - Raw projection value.
+ * @returns the value as a context-pressure view, or `undefined`.
+ */
+export function asContextPressureView(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const fields = ['pressureTokens', 'projectedTokens', 'contextWindow'];
+    let known = false;
+    for (const field of fields) {
+        const raw = record[field];
+        if (raw === undefined)
+            continue;
+        if (finiteNumber(raw) === undefined)
+            return undefined;
+        known = true;
+    }
+    return known ? value : undefined;
+}
+/**
+ * The official numerator: `projectedTokens ?? pressureTokens`.
+ *
+ * This is the precedence `ui-conversation/src/client/context-occupancy.ts`
+ * uses. `projectedTokens` is preferred because it is the only field that
+ * answers for the next request; `pressureTokens` is the bare sample and is all
+ * a session whose surface total is unknown can offer.
+ * @param view - The projection value.
+ * @returns the occupancy numerator, or `undefined` before any provider sample.
+ */
+export function contextPressureUsedTokens(view) {
+    return view.projectedTokens ?? view.pressureTokens;
+}
+/**
+ * Resolve the ONE occupancy reading the footer, the segmented bar, the working
+ * line's pressure prefix, the status commands and the context-low warning share.
+ *
+ * DIVERGENCE FROM THE OFFICIAL RENDERER (deliberate, see the PR body): the Web
+ * UI renders nothing when the projection carries neither pressure nor a window.
+ * The TUI keeps its pre-projection sample readout instead, so a bare
+ * `cordis.yml` composition (no dsh-base bundle ⇒ no token meter) does not
+ * silently lose a number it has always shown; {@link ContextOccupancy.source}
+ * names which path answered. A composition WITH a meter — every normal
+ * deployment, where the base bundle mounts token-meter on the host plane —
+ * takes the projection branch as soon as a request reports usage, and the
+ * fallback becomes unreachable.
+ * @param projected - Cached `contextPressure` value, `undefined` without a meter.
+ * @param sample - Last settled request's billed usage (the fallback numerator).
+ * @param requestWindow - `request/context` capacity (the fallback denominator).
+ * @returns the reading, or `undefined` when neither path knows anything.
+ */
+export function resolveContextOccupancy(projected, sample, requestWindow) {
+    const contextWindow = projected?.contextWindow ?? requestWindow;
+    const projectedUsed = projected === undefined ? undefined : contextPressureUsedTokens(projected);
+    if (projectedUsed !== undefined) {
+        return { usedTokens: projectedUsed, contextWindow, source: 'projection' };
+    }
+    if (sample === undefined)
+        return undefined;
+    return {
+        usedTokens: sample.input + sample.cacheRead + sample.cacheWrite,
+        contextWindow,
+        source: 'sample',
+    };
+}
+/**
+ * The latest `contextPressure` value for the session on screen.
+ *
+ * Effectively single-current, mirroring {@link ActivityStore}: binding a
+ * session names the one the UI shows, and every other id is dropped — the
+ * projection feed is host-wide, and a background session must not overwrite the
+ * footer of the session on screen.
+ *
+ * The store holds VALUES, never sessions to re-read: the feed delivers the
+ * whole value, so there is nothing to poll. Only {@link seed} reads a snapshot,
+ * and only because a resumed session's value may not have changed (and
+ * therefore never been published) since it was last folded.
+ */
+export class ContextOccupancyStore {
+    values = new Map();
+    listeners = new Set();
+    /** The session the UI is showing (the last {@link seed}); the only id kept. */
+    currentId;
+    /** Session object behind {@link currentId}, so a late registry can still seed. */
+    currentSession;
+    /** Host registry, remembered so a bind can read a baseline on demand. */
+    registry;
+    /** Read failures are reported once: a broken registry must not spam the log. */
+    warned = false;
+    warn;
+    constructor(warn) {
+        this.warn = warn;
+    }
+    /**
+     * Remember the host registry. A registry that arrives after the session bound
+     * is immediately used to read the baseline {@link seed} could not: the unit
+     * and its registry are mounted by other plugins, so the order is not ours.
+     * @param registry - The host projection registry.
+     */
+    attachRegistry(registry) {
+        this.registry = registry;
+        if (this.currentSession !== undefined)
+            this.seed(this.currentSession);
+    }
+    /**
+     * Bind one session and read its current projection value once.
+     *
+     * The bind also defines the session on screen: every other id is pruned, so a
+     * later background event can no longer fill this store.
+     * @param session - Session being bound.
+     */
+    seed(session) {
+        if (session === null || session === undefined)
+            return;
+        this.currentId = String(session.id);
+        this.currentSession = session;
+        this.pruneToCurrent();
+        const registry = this.registry;
+        if (registry === undefined)
+            return;
+        try {
+            const values = registry.snapshot(session, [CONTEXT_PRESSURE_PROJECTION_KEY]).values;
+            this.remember(this.currentId, asContextPressureView(values[CONTEXT_PRESSURE_PROJECTION_KEY]));
+        }
+        catch (error) {
+            this.noteReadFailure(error);
+        }
+    }
+    /**
+     * Record one value from the projection change feed.
+     * @param sessionId - Session the value belongs to.
+     * @param value - The published wire value.
+     */
+    update(sessionId, value) {
+        this.remember(sessionId, asContextPressureView(value));
+    }
+    /** The current value for one session, stable between updates. */
+    read(sessionId) {
+        return this.values.get(sessionId);
+    }
+    /** Subscribe to value changes; returns the unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /**
+     * Report a failed registry read once. The sink is the composition root's
+     * logger — this module stays free of cordis types.
+     * @param error - What the failed read threw.
+     */
+    noteReadFailure(error) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        const detail = error instanceof Error ? error.message : String(error);
+        this.warn?.(`dsh-tui: context-pressure projection read failed: ${detail}`);
+    }
+    /** Store one already-narrowed value for the current session and emit on change. */
+    remember(sessionId, view) {
+        if (this.currentId !== undefined && sessionId !== this.currentId)
+            return;
+        const previous = this.values.get(sessionId);
+        if (view === undefined) {
+            if (previous === undefined)
+                return;
+            this.values.delete(sessionId);
+            this.emit();
+            return;
+        }
+        // The host reuses the view reference while its state is unchanged
+        // (`Object.is` suppression in the registry), so an identity check is the
+        // whole change test.
+        if (previous === view)
+            return;
+        this.values.set(sessionId, view);
+        this.emit();
+    }
+    /** Drop every id that is not the current one; emit when a value went. */
+    pruneToCurrent() {
+        if (this.currentId === undefined)
+            return;
+        let removed = false;
+        for (const id of [...this.values.keys()]) {
+            if (id === this.currentId)
+                continue;
+            this.values.delete(id);
+            removed = true;
+        }
+        if (removed)
+            this.emit();
+    }
+    emit() {
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+/**
+ * Wire one store to the host's projection registry.
+ *
+ * Registration is deferred through `inject` because the plugin that *publishes*
+ * the unit is mounted alongside this one: the registry may not exist yet, and
+ * the unit may not be registered until later still. Both absences are normal —
+ * a composition without the token meter simply never fills the store, and the
+ * channel falls back to its own sample.
+ *
+ * The feed is event-driven and carries the whole value, so a change costs one
+ * narrow + one map write. A long resumed session (thousands of replayed events)
+ * therefore pays O(changes of this unit) and never a per-event fold; rendering
+ * pays a map lookup, never a `snapshot()`.
+ * @param ctx - Host context of the composition root.
+ * @param store - Store to fill.
+ */
+export function attachContextPressureProjection(ctx, store) {
+    ctx.inject(['sessionProjections'], ((projectionCtx) => {
+        const registry = projectionCtx.sessionProjections;
+        if (registry === undefined)
+            return;
+        store.attachRegistry(registry);
+        let offFeed;
+        try {
+            offFeed = registry.onChanged((session, key, value) => {
+                if (key !== CONTEXT_PRESSURE_PROJECTION_KEY)
+                    return;
+                store.update(String(session.id), value);
+            });
+        }
+        catch (error) {
+            store.noteReadFailure(error);
+        }
+        // The cleanup belongs to the injected fiber, not the outer ctx: a service
+        // re-provide re-runs the callback above, and registering on the outer ctx
+        // would stack feed listeners (the old listener's disposer would only run
+        // when the whole composition root goes down).
+        projectionCtx.effect(() => () => {
+            offFeed?.();
+        }, 'dsh-tui context-pressure projection feed');
+    }));
+}
+/**
+ * Create the composition root's occupancy store and wire it to the host.
+ *
+ * Unlike the activity store there is no config gate: occupancy feeds the
+ * footer's ctx field, the segmented bar and the context-low warning, so hiding
+ * one surface must not stop the others from being correct.
+ * @param ctx - Host context of the composition root.
+ * @returns the store the channel reads from.
+ */
+export function createContextOccupancyStore(ctx) {
+    const store = new ContextOccupancyStore(message => { ctx.logger.warn(message); });
+    attachContextPressureProjection(ctx, store);
+    return store;
+}