@itookit/dsht 0.3.8 → 0.5.1

package/dist/session/history.d.ts

@@ -14,24 +14,6 @@ export interface HistoryRow {
     /** Draw the row on the theme's local-command bar, used by `!` commands. */
     highlight?: boolean;
 }
-/** Wrap text into rows with the per-kind trimming rule.
- * @param text - Text to wrap.
- * @param width - Available terminal columns.
- * @param kind - Part kind, which decides whether wrapped lines are trimmed.
- * @param seq - Durable sequence, for committed parts.
- * @returns The wrapped rows.
- */
-/** Wrap plain local text into terminal rows, preserving its own whitespace.
- *
- * Command output is aligned by spaces and indented by stack traces, so this never collapses runs of
- * whitespace the way tool summaries do; only the terminal width decides where a row breaks.
- * @param text - Raw text, possibly containing newlines.
- * @param width - Available terminal columns.
- * @param kind - Row kind used for coloring.
- * @param highlight - Whether the rows are a local command line drawn on the command bar.
- * @returns One row per wrapped terminal line; empty text yields one empty row.
- */
-export declare function plainRows(text: string, width: number, kind: RowKind, highlight?: boolean): HistoryRow[];
 /** Drop all terminal rows and layout metadata for an evicted or inactive transcript.
  * @param transcript - Transcript whose previously returned layout is no longer used.
  */
@@ -59,6 +41,12 @@ export declare function layoutStats(transcript: Transcript): {
  * @param liveReasoning - Fold mode for completed live blocks; below 60 content columns it also folds active reasoning.
  * @returns Row count, sequence offsets, and a viewport reader; `lines` materializes all rows for exports only.
  */
+/** Plain view of one laid-out record: the projection engine's only public product.
+ *
+ * It exposes rows through `viewport` and message positions through `offsets`, so a caller can render
+ * a window without holding the record itself.
+ */
+export type SessionRender = ReturnType<typeof historyLayout>;
 export declare function historyLayout(transcript: Transcript, width: number, reasoning?: Reasoning, overrides?: ReadonlySet<number>, liveReasoning?: Reasoning): {
     messages: Message[];
     offsets: Map<number, number>;

package/dist/session/history.js

@@ -1,7 +1,7 @@
 /** Indexed semantic history with bounded terminal-row caching and viewport-only materialization. */
 import wrapAnsi from 'wrap-ansi';
-import { toolLine } from "./transcript.js";
 import { hasMarkdown, markdownRows } from "./markdown.js";
+import { toolLine } from "../text.js";
 /** A session owns one layout cache; dropped sessions release their entire cache. */
 class LayoutIndex {
     width;
@@ -140,21 +140,6 @@ const liveRows = new WeakMap();
  * @param seq - Durable sequence, for committed parts.
  * @returns The wrapped rows.
  */
-/** Wrap plain local text into terminal rows, preserving its own whitespace.
- *
- * Command output is aligned by spaces and indented by stack traces, so this never collapses runs of
- * whitespace the way tool summaries do; only the terminal width decides where a row breaks.
- * @param text - Raw text, possibly containing newlines.
- * @param width - Available terminal columns.
- * @param kind - Row kind used for coloring.
- * @param highlight - Whether the rows are a local command line drawn on the command bar.
- * @returns One row per wrapped terminal line; empty text yields one empty row.
- */
-export function plainRows(text, width, kind, highlight = false) {
-    const columns = Math.max(1, width);
-    const wrapped = wrapAnsi(text === '' ? ' ' : text, columns, { hard: true, trim: false });
-    return wrapped.split('\n').map(line => ({ text: line, kind, ...(highlight ? { highlight: true } : {}) }));
-}
 function wrapRows(text, width, kind, seq) {
     return wrapAnsi(text, width, { hard: true, trim: !['tool', 'success', 'error'].includes(kind) })
         .split('\n').map(text => ({ text, kind, seq }));
@@ -295,14 +280,6 @@ export function layoutStats(transcript) {
         return undefined;
     return { ...index.stats(), liveWraps: index.liveWraps.size, liveMarkdown: index.liveMarkdown.size };
 }
-/** Lay out an indexed conversation without concatenating its historical rows on every stream frame.
- * @param transcript - Selected session's semantic content and unfinished assistant output.
- * @param width - Available terminal columns.
- * @param reasoning - Global committed/completed reasoning fold mode.
- * @param overrides - Sequences whose fold mode differs from the global mode; replace the set on changes.
- * @param liveReasoning - Fold mode for completed live blocks; below 60 content columns it also folds active reasoning.
- * @returns Row count, sequence offsets, and a viewport reader; `lines` materializes all rows for exports only.
- */
 export function historyLayout(transcript, width, reasoning = 'row', overrides = noOverrides, liveReasoning = reasoning) {
     let index = indexes.get(transcript);
     if (!index || index.width !== width || index.reasoning !== reasoning || index.overrides !== overrides) {

package/dist/session/index.d.ts

@@ -1,6 +1,9 @@
 /** Session domain: the selected session, its transcript, layout, telemetry and navigation. */
 export { SessionController } from './controller.ts';
-export { contentText, toolLine, Transcript } from './transcript.ts';
+export { SessionMutationGate } from './mutation-gate.ts';
+export type { MutationAdmission, MutationLane } from './mutation-gate.ts';
+export { contentText, Transcript } from './transcript.ts';
+export { toolLine } from '../text.ts';
 export type { LivePhase, Message, MessagePart, ThoughtEntry } from './transcript.ts';
 export { historyLayout, layoutStats, releaseHistoryLayout } from './history.ts';
 export { markdownCacheStats } from './markdown.ts';
@@ -10,9 +13,11 @@ export type { QueuedInput } from './telemetry.ts';
 export { DEFAULT_HISTORY_LIMITS, historyLimits } from './memory.ts';
 export type { HistoryLimits } from './memory.ts';
 export { DEFAULT_PROMPT_LIMITS, promptText, PromptIndex, SessionInfo } from './info.ts';
-export type { ComposerState, InteractionState, ModelState, OptionState, PanelState, PromptEntry, PromptLimits, PromptRecord, ReferenceState, ViewState } from './info.ts';
-export { navigationCommand, resolveTarget, sessionLabel } from './navigation.ts';
-export { activeReference, fileMention, fileReferences } from './references.ts';
+export type { InteractionState, ModelState, OptionState, PanelState, PromptEntry, PromptLimits, PromptRecord, } from './info.ts';
+export { resolveTarget } from './navigation.ts';
+export { sessionLabel } from '../session-title.ts';
+export { fileReferences } from './references.ts';
+export { activeReference, fileMention } from '../references.ts';
 export type { FileReference } from './references.ts';
 export { saveSessionLog } from './export.ts';
 export type { HistorySearch, RemovalTarget } from './types.ts';

package/dist/session/index.js

@@ -1,11 +1,15 @@
 /** Session domain: the selected session, its transcript, layout, telemetry and navigation. */
 export { SessionController } from "./controller.js";
-export { contentText, toolLine, Transcript } from "./transcript.js";
+export { SessionMutationGate } from "./mutation-gate.js";
+export { contentText, Transcript } from "./transcript.js";
+export { toolLine } from "../text.js";
 export { historyLayout, layoutStats, releaseHistoryLayout } from "./history.js";
 export { markdownCacheStats } from "./markdown.js";
 export { Telemetry } from "./telemetry.js";
 export { DEFAULT_HISTORY_LIMITS, historyLimits } from "./memory.js";
 export { DEFAULT_PROMPT_LIMITS, promptText, PromptIndex, SessionInfo } from "./info.js";
-export { navigationCommand, resolveTarget, sessionLabel } from "./navigation.js";
-export { activeReference, fileMention, fileReferences } from "./references.js";
+export { resolveTarget } from "./navigation.js";
+export { sessionLabel } from "../session-title.js";
+export { fileReferences } from "./references.js";
+export { activeReference, fileMention } from "../references.js";
 export { saveSessionLog } from "./export.js";

package/dist/session/info.d.ts

@@ -1,17 +1,5 @@
-/** Session-owned prompt index: every user prompt of the selected session, plus its recall cursor.
- *
- * The index replaces a plain bounded recall buffer. Each durable entry carries the sequence it came
- * from, so an entry evicted by the budgets stays recoverable: the loaded window refills anything the
- * transcript still holds, and `session/page` refetches anything older than the window. Budgets
- * therefore bound memory without deciding reachability — which is what a base-200 buffer got wrong.
- *
- * Locally submitted slash commands never become durable records, so they are retained too, marked as
- * non-durable. A durable echo of a locally recorded prompt upgrades that entry instead of adding a
- * second copy, keeping the refill boundary (the oldest durable sequence) exact.
- */
-import { type Reasoning } from './history.ts';
 import { Transcript } from './transcript.ts';
-import type { HistorySearch } from './types.ts';
+import type { AnswerValue, HistorySearch } from './types.ts';
 import type { ObjectValue } from '../transport/wire.ts';
 /** A durable user prompt as the transcript reports it, before retention. */
 export interface PromptRecord {
@@ -31,49 +19,24 @@ export interface PromptLimits {
 export declare const DEFAULT_PROMPT_LIMITS: PromptLimits;
 /** Flatten one transcript prompt into the single line the composer recalls. */
 export declare function promptText(value: string): string;
-/** The selected session's composer: its draft, the caret in it, and a draft a dialog parked aside. */
-export interface ComposerState {
-    draft: string;
-    cursor: number;
-    parked: string;
-}
-/** How the selected session's record is being read: which window, where, and what is expanded.
- *
- * Everything here changes how the record renders, which is why it is session state rather than a
- * transient panel flag; the record's content stays in `Transcript`. `window` is a strong reference
- * released by `closeWindow`, and the layout cache keyed by it is a weak one.
- */
-export interface ViewState {
-    /** Detached record shown instead of the live transcript while reading jumped-to history. */
-    window?: Transcript;
-    scroll: number;
-    /** Reading protection: reclamation pauses until the reader returns to the live end. */
-    pinned: boolean;
-    /** Message sequences whose reasoning is expanded beyond the default fold. */
-    folds: ReadonlySet<number>;
-    /** Fold mode for the live attempt's completed reasoning. */
-    liveReasoning: Reasoning;
-}
-/** Composer-adjacent `@` reference menu: the highlighted row and the draft that dismissed it. */
-export interface ReferenceState {
-    index: number;
-    dismissed?: string;
-}
 /** Model dialog step: the catalog plus the provider or model being inspected. */
 export interface ModelState {
     catalog: ObjectValue;
     provider?: string;
     model?: ObjectValue;
 }
-/** Panels the reader opened for the selected session.
+/** Panels the reader opened; visibility and query text only, so the UI owns them.
  *
- * Only visibility and query text: every panel's rows come from the record, so closing one loses
- * nothing and a session switch may clear all of it. The row cursor inside a panel is not here — it
- * is focus, held by `Picker` and reset through its `key`.
+ * One container rather than one flag per call site, so the composition root has a single panel set
+ * to gate keys, reset on a session switch and close from a command. Every session panel's rows come
+ * from the selected record and its cursor is focus held by `Picker`; the one exception is `prompts`,
+ * which lists a client-global file and is therefore not derived from the record.
  */
 export interface PanelState {
     thoughts: boolean;
     queue: boolean;
+    /** Saved shortcut prompts opened by `/prompt`; a client-global list, kept here for one registry. */
+    prompts?: boolean;
     model?: ModelState;
     history?: {
         query: string;
@@ -98,7 +61,7 @@ export interface OptionState {
  *  `SessionController.interactions`, which is derived per session on every publish.
  */
 export interface InteractionState {
-    answers: Record<string, ObjectValue[]>;
+    answers: Record<string, AnswerValue['answers']>;
     option?: OptionState;
     approval?: {
         eventId: string;
@@ -107,7 +70,7 @@ export interface InteractionState {
 }
 /** Client-owned state of the selected session, reset whenever another session is opened.
  *
- * It holds the record, the prompt index, the composer, the reading view and the local interaction
+ * It holds the record, the prompt index, the reading view and the local interaction
  * state because all five belong to one session and none of them is owned by the host beyond what the
  * record mirrors; everything derivable from `Telemetry` or `CostLedger` stays out (see the design's
  * §5.7.6). The record is referenced here and nowhere else, so "the selected session" has one entry.
@@ -117,11 +80,9 @@ export declare class SessionInfo {
     /** The selected session's record. Replaced — never mutated in place — when another session opens. */
     record: Transcript;
     readonly prompts: PromptIndex;
-    readonly composer: ComposerState;
-    readonly view: ViewState;
+    /** Detached history window the reader jumped to; released by `closeWindow` and `reset`. */
+    window?: Transcript;
     readonly interaction: InteractionState;
-    readonly reference: ReferenceState;
-    readonly panels: PanelState;
     constructor(sessionId?: string);
     /** Forget everything a previous session owned, keeping this instance identity-stable for `State`. */
     reset(sessionId?: string): void;
@@ -143,6 +104,12 @@ export declare class PromptIndex {
     private shed;
     private position;
     private draft;
+    /** Prompts the client sent on the operator's behalf; their durable echo never enters recall.
+     *
+     * Kept across `reset()` so re-opening the session in the same process stays clean, and bounded
+     * because an agent loop can send a prompt per attempt.
+     */
+    private readonly internal;
     constructor(limits?: PromptLimits);
     /** Retained entry count, so a caller can tell an empty index from a parked cursor. */
     get length(): number;
@@ -167,8 +134,14 @@ export declare class PromptIndex {
      * live window holds, so the lazy backward step could not recover them.
      */
     markComplete(): void;
-    /** Forget one session's prompts and cursor. */
+    /** Forget one session's prompts and cursor; client-generated suppression is process-wide. */
     reset(): void;
+    /** Remember one prompt the client sent itself, so its durable echo never enters recall.
+     *
+     * An agent loop submits many turns; without this they would crowd out what the operator typed.
+     * @param value - Prompt text the client sent on the operator's behalf.
+     */
+    suppress(value: string): void;
     /** Fold one transcript scan: its prompts, plus the watermark it covered.
      *
      * The watermark advances even when the scan found no prompt, so a turn of assistant and tool

package/dist/session/info.js

@@ -15,11 +15,13 @@ import { Transcript } from "./transcript.js";
 export const DEFAULT_PROMPT_LIMITS = { maxEntries: 2000, maxBytes: 512 * 1024 };
 /** Longest single prompt worth recalling; a larger one is skipped rather than truncated in place. */
 const MAX_ENTRY_CHARS = 128 * 1024;
+/** Client-generated prompts remembered for recall suppression; a bounded run needs far fewer. */
+const MAX_INTERNAL_PROMPTS = 512;
 /** Flatten one transcript prompt into the single line the composer recalls. */
 export function promptText(value) { return value.replace(/\r?\n/g, ' ').trim(); }
 /** Client-owned state of the selected session, reset whenever another session is opened.
  *
- * It holds the record, the prompt index, the composer, the reading view and the local interaction
+ * It holds the record, the prompt index, the reading view and the local interaction
  * state because all five belong to one session and none of them is owned by the host beyond what the
  * record mirrors; everything derivable from `Telemetry` or `CostLedger` stays out (see the design's
  * §5.7.6). The record is referenced here and nowhere else, so "the selected session" has one entry.
@@ -29,11 +31,9 @@ export class SessionInfo {
     /** The selected session's record. Replaced — never mutated in place — when another session opens. */
     record = new Transcript();
     prompts = new PromptIndex();
-    composer = { draft: '', cursor: 0, parked: '' };
-    view = { scroll: 0, pinned: false, folds: new Set(), liveReasoning: 'row' };
+    /** Detached history window the reader jumped to; released by `closeWindow` and `reset`. */
+    window;
     interaction = { answers: {} };
-    reference = { index: 0 };
-    panels = { thoughts: false, queue: false };
     constructor(sessionId = '') {
         this.sessionId = sessionId;
     }
@@ -45,32 +45,18 @@ export class SessionInfo {
         this.record.dispose();
         this.record = new Transcript();
         this.prompts.reset();
-        this.composer.draft = '';
-        this.composer.cursor = 0;
-        this.composer.parked = '';
-        this.view.scroll = 0;
-        this.view.pinned = false;
-        this.view.folds = new Set();
-        this.view.liveReasoning = 'row';
         this.interaction.answers = {};
         this.interaction.option = undefined;
         this.interaction.approval = undefined;
-        this.reference.index = 0;
-        this.reference.dismissed = undefined;
-        this.panels.thoughts = false;
-        this.panels.queue = false;
-        this.panels.model = undefined;
-        this.panels.history = undefined;
-        this.panels.search = undefined;
     }
     /** Release the detached history window, if the reader has one open. */
     closeWindow() {
-        const window = this.view.window;
+        const window = this.window;
         if (!window)
             return;
         releaseHistoryLayout(window);
         window.dispose();
-        this.view.window = undefined;
+        this.window = undefined;
     }
 }
 /** Seq-ordered prompts with a recall cursor, owned by the selected session.
@@ -88,6 +74,12 @@ export class PromptIndex {
     shed = false;
     position;
     draft = '';
+    /** Prompts the client sent on the operator's behalf; their durable echo never enters recall.
+     *
+     * Kept across `reset()` so re-opening the session in the same process stays clean, and bounded
+     * because an agent loop can send a prompt per attempt.
+     */
+    internal = new Set();
     constructor(limits = DEFAULT_PROMPT_LIMITS) {
         this.limits = limits;
     }
@@ -122,7 +114,7 @@ export class PromptIndex {
      */
     markComplete() { if (!this.shed)
         this.complete = true; }
-    /** Forget one session's prompts and cursor. */
+    /** Forget one session's prompts and cursor; client-generated suppression is process-wide. */
     reset() {
         this.entries = [];
         this.bytes = 0;
@@ -132,6 +124,24 @@ export class PromptIndex {
         this.position = undefined;
         this.draft = '';
     }
+    /** Remember one prompt the client sent itself, so its durable echo never enters recall.
+     *
+     * An agent loop submits many turns; without this they would crowd out what the operator typed.
+     * @param value - Prompt text the client sent on the operator's behalf.
+     */
+    suppress(value) {
+        const text = promptText(value);
+        if (!text)
+            return;
+        this.internal.delete(text);
+        this.internal.add(text);
+        while (this.internal.size > MAX_INTERNAL_PROMPTS) {
+            const oldest = this.internal.values().next().value;
+            if (oldest === undefined)
+                break;
+            this.internal.delete(oldest);
+        }
+    }
     /** Fold one transcript scan: its prompts, plus the watermark it covered.
      *
      * The watermark advances even when the scan found no prompt, so a turn of assistant and tool
@@ -154,7 +164,10 @@ export class PromptIndex {
      * @param value - Submitted command text; consecutive repeats coalesce.
      */
     record(value) {
-        const entry = { seq: this.newestSeq, text: promptText(value), durable: false };
+        const text = promptText(value);
+        if (this.internal.has(text))
+            return;
+        const entry = { seq: this.newestSeq, text, durable: false };
         if (!this.retainable(entry) || this.entries.at(-1)?.text === entry.text)
             return;
         this.entries.push(entry);
@@ -167,7 +180,7 @@ export class PromptIndex {
      */
     prepend(values) {
         const older = values.map(value => ({ seq: value.seq, text: promptText(value.text), durable: true }))
-            .filter(value => this.retainable(value));
+            .filter(value => !this.internal.has(value.text) && this.retainable(value));
         if (!older.length)
             return 0;
         this.entries = [...older, ...this.entries];
@@ -213,7 +226,8 @@ export class PromptIndex {
     /** Retain one durable prompt; a durable echo upgrades a local entry instead of duplicating it. */
     push(value) {
         const entry = { seq: value.seq, text: promptText(value.text), durable: true };
-        if (!this.retainable(entry))
+        // A prompt the client itself sent (an agent loop) is durable history, but not composer recall.
+        if (this.internal.has(entry.text) || !this.retainable(entry))
             return;
         const last = this.entries.at(-1);
         if (last && last.text === entry.text) {

package/dist/session/markdown.js

@@ -5,7 +5,7 @@ import stringWidth from 'string-width';
 import wrapAnsi from 'wrap-ansi';
 import { stripVTControlCharacters } from 'node:util';
 import { decodeHTML } from 'entities';
-import { safeText } from "../transport/wire.js";
+import { safeText } from "../text.js";
 import { renderMath } from "./math.js";
 const parser = new Marked({ gfm: true });
 // Math is tokenized before Markdown escapes, but after fenced and inline code have claimed their source.

package/dist/session/math.js

@@ -8,7 +8,7 @@ import { TextNode } from '@mathjax/src/js/core/MmlTree/MmlNode.js';
 import { SerializedMmlVisitor } from '@mathjax/src/js/core/MmlTree/SerializedMmlVisitor.js';
 import '@mathjax/src/js/input/tex/base/BaseConfiguration.js';
 import '@mathjax/src/js/input/tex/ams/AmsConfiguration.js';
-import { safeText } from "../transport/wire.js";
+import { safeText } from "../text.js";
 RegisterHTMLHandler(liteAdaptor());
 const superscripts = Object.fromEntries([...('0123456789+-=()ni')].map((c, i) => [c, [...'⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻⁼⁽⁾ⁿⁱ'][i]]));
 const subscripts = Object.fromEntries([...'0123456789+-=()aehijklmnoprstuvx'].map((c, i) => [c, [...'₀₁₂₃₄₅₆₇₈₉₊₋₌₍₎ₐₑₕᵢⱼₖₗₘₙₒₚᵣₛₜᵤᵥₓ'][i]]));

package/dist/session/mutation-gate.d.ts

@@ -0,0 +1,51 @@
+/** One session's mutation admission order, with a control lane that overtakes the normal waiters.
+ *
+ * The gate serializes the **admission** of a mutation — checking state, deciding, and issuing the
+ * request — not the remote mutation itself. A section therefore returns as soon as the request is
+ * issued, and the caller awaits the host's answer outside the gate: a `/compact` can take minutes, and
+ * holding the gate for it would make `cancel` wait for exactly the operation it exists to interrupt.
+ * The `return dispatch()` below is what enforces that: the gate releases when the section *returns*,
+ * so even an `async` section holds it only up to its first `await`.
+ *
+ * Two lanes:
+ *
+ * * `normal` — a prompt, steering, a host command, an answer, a queue removal: arrival order;
+ * * `control` — `cancelTurn`/`interrupt` and `/loop stop`: waits only for the section already running,
+ *   so it is admitted ahead of every normal admission that is still waiting.
+ *
+ * The key is the **target** session, not the selected one: cancelling a forked verifier addresses the
+ * verifier's own session, and that must not queue behind the reviewed session's writes.
+ */
+/** Which queue one mutation admission joins. */
+export type MutationLane = 'normal' | 'control';
+/** One admission, as the gate reports it so the trace can answer "who dispatched first". */
+export interface MutationAdmission {
+    /** Session the mutation targets; never inferred from the selection. */
+    readonly sessionId: string;
+    /** Lane the admission used. */
+    readonly lane: MutationLane;
+    /** Whether another admission already held this session's gate when this one arrived. */
+    readonly waited: boolean;
+}
+/** Serializes one session's mutation admissions. */
+export declare class SessionMutationGate {
+    private readonly report?;
+    private readonly lanes;
+    /** @param report - Optional observer, called once per admission in dispatch order. */
+    constructor(report?: ((admission: MutationAdmission) => void) | undefined);
+    /** Wait for this session's turn, then run one section inside the gate.
+     *
+     * `dispatch` must decide and **issue**: return the promise the caller will await, rather than
+     * awaiting it here, or the gate stays held for the whole remote mutation.
+     * @param sessionId - Target session the mutation belongs to.
+     * @param lane - `control` overtakes waiting normal admissions; `normal` keeps arrival order.
+     * @param dispatch - Synchronous decision plus request issue.
+     * @returns What `dispatch` returned; a returned promise is adopted, so the caller may await the
+     *   host's answer without holding the gate.
+     */
+    admit<T>(sessionId: string, lane: MutationLane, dispatch: () => T): Promise<T>;
+    /** Take the gate now, or queue for it behind the running section. */
+    private acquire;
+    /** Hand the gate to the next waiter, control first, or free it. */
+    private release;
+}

package/dist/session/mutation-gate.js

@@ -0,0 +1,73 @@
+/** One session's mutation admission order, with a control lane that overtakes the normal waiters.
+ *
+ * The gate serializes the **admission** of a mutation — checking state, deciding, and issuing the
+ * request — not the remote mutation itself. A section therefore returns as soon as the request is
+ * issued, and the caller awaits the host's answer outside the gate: a `/compact` can take minutes, and
+ * holding the gate for it would make `cancel` wait for exactly the operation it exists to interrupt.
+ * The `return dispatch()` below is what enforces that: the gate releases when the section *returns*,
+ * so even an `async` section holds it only up to its first `await`.
+ *
+ * Two lanes:
+ *
+ * * `normal` — a prompt, steering, a host command, an answer, a queue removal: arrival order;
+ * * `control` — `cancelTurn`/`interrupt` and `/loop stop`: waits only for the section already running,
+ *   so it is admitted ahead of every normal admission that is still waiting.
+ *
+ * The key is the **target** session, not the selected one: cancelling a forked verifier addresses the
+ * verifier's own session, and that must not queue behind the reviewed session's writes.
+ */
+/** Serializes one session's mutation admissions. */
+export class SessionMutationGate {
+    report;
+    lanes = new Map();
+    /** @param report - Optional observer, called once per admission in dispatch order. */
+    constructor(report) {
+        this.report = report;
+    }
+    /** Wait for this session's turn, then run one section inside the gate.
+     *
+     * `dispatch` must decide and **issue**: return the promise the caller will await, rather than
+     * awaiting it here, or the gate stays held for the whole remote mutation.
+     * @param sessionId - Target session the mutation belongs to.
+     * @param lane - `control` overtakes waiting normal admissions; `normal` keeps arrival order.
+     * @param dispatch - Synchronous decision plus request issue.
+     * @returns What `dispatch` returned; a returned promise is adopted, so the caller may await the
+     *   host's answer without holding the gate.
+     */
+    async admit(sessionId, lane, dispatch) {
+        const state = this.lanes.get(sessionId) ?? { busy: false, control: [], normal: [] };
+        this.lanes.set(sessionId, state);
+        const waited = state.busy;
+        await this.acquire(state, lane);
+        this.report?.({ sessionId, lane, waited });
+        try {
+            return dispatch();
+        }
+        finally {
+            this.release(sessionId, state);
+        }
+    }
+    /** Take the gate now, or queue for it behind the running section. */
+    async acquire(state, lane) {
+        if (!state.busy) {
+            state.busy = true;
+            return;
+        }
+        // The waiter that is woken inherits the gate: `busy` stays true across the handoff, so an
+        // admission arriving during it queues instead of overtaking the waiter already promised the turn.
+        await new Promise(resolve => (lane === 'control' ? state.control : state.normal).push(resolve));
+    }
+    /** Hand the gate to the next waiter, control first, or free it. */
+    release(sessionId, state) {
+        const next = state.control.shift() ?? state.normal.shift();
+        if (next !== undefined) {
+            next();
+            return;
+        }
+        state.busy = false;
+        // A lane nobody is waiting for would otherwise stay behind for the life of the process, and long
+        // runs create a session per verification.
+        if (this.lanes.get(sessionId) === state)
+            this.lanes.delete(sessionId);
+    }
+}

package/dist/session/navigation.d.ts

@@ -1,91 +1,4 @@
-/** Shared display names and unambiguous slash-command target resolution. */
-import { type ObjectValue } from '../transport/wire.ts';
-/** Parse workspace and resume navigation, including their long aliases. */
-export declare function navigationCommand(value: string): {
-    kind: 'workspace' | 'session';
-    query?: string;
-} | undefined;
-/** Resolve the host's title projection, falling back to the session ID. */
-export declare function sessionLabel(session: ObjectValue): string;
+/** Unambiguous slash-command target resolution and host title projection. */
+import { type ObjectValue } from '../json.ts';
 /** Match an exact ID or name before a unique ID prefix; never choose an ambiguous target. */
 export declare function resolveTarget(items: ObjectValue[], query: string, id: string, names: (item: ObjectValue) => string[]): ObjectValue;
-/** User-visible activity of one session, most actionable first.
- *
- * `needs` is the only state that asks the user to do something, and it outranks the host's running
- * flag because a turn waiting on an answer is running only in the mechanical sense. `blank` stays a
- * marker for a session that never sent a turn, but it is not a status and never enters a rollup.
- */
-export type SessionState = 'needs' | 'running' | 'idle' | 'blank';
-/** Classify one session from the host's list summary; nothing is inferred from silence.
- * @param session - Session summary from `session/list`.
- * @param pending - Whether this client holds an unanswered interaction for that session.
- * @returns Needs-you while an answer is owed, running while its agent works, otherwise idle or blank.
- */
-export declare function sessionState(session: ObjectValue, pending?: boolean): SessionState;
-/** Leading marker per state: a question mark, a working clock, a filled dot, and an unused circle. */
-export declare const SESSION_MARKERS: Record<SessionState, string>;
-/** One word per state, so every screen names the same state the same way. */
-export declare const STATE_LABELS: Record<SessionState, string>;
-/** Coarse age of a session's last activity, so the column stays steady between list refreshes.
- * @param time - Epoch milliseconds of the last activity, when the summary reported one.
- * @param now - Current epoch milliseconds.
- * @returns `now`, minutes, hours or days.
- */
-export declare function activityAge(time: number | undefined, now: number): string;
-/** Status cell for one session row: its state marker and the age of its last activity.
- * @param session - Session summary from `session/list`.
- * @param now - Current epoch milliseconds.
- * @param pending - Whether this client holds an unanswered interaction for that session.
- * @returns Marker with an optional age, without a trailing space when unknown.
- */
-export declare function sessionStatus(session: ObjectValue, now: number, pending?: boolean): string;
-/** States a workspace rollup reports, most actionable first. */
-export declare const ROLLUP_STATES: readonly ["needs", "running", "idle"];
-/** One state a workspace rollup reports. */
-export type RollupState = (typeof ROLLUP_STATES)[number];
-/** One counted state of a workspace rollup. */
-export interface RollupCount {
-    state: RollupState;
-    count: number;
-}
-/** How much room a rollup has for words. */
-export type RollupStyle = 'words' | 'badges';
-/** Count the sessions of one workspace by the state each reports.
- *
- * Blank sessions are counted by neither a badge nor a word: a session that never sent a turn is the
- * absence of activity, and listing it beside real work only makes the rollup harder to read.
- * @param sessions - Sessions whose `sessionIds` belong to the workspace.
- * @param pending - Session IDs this client holds an unanswered interaction for.
- * @returns One count per state that occurs, most actionable first, or an empty list.
- */
-export declare function workspaceCounts(sessions: readonly ObjectValue[], pending?: ReadonlySet<string>): RollupCount[];
-/** Render one rollup as separately coloured cells.
- *
- * Each cell after the first carries the separator that joins it to the previous one, so a caller can
- * colour the cells independently without losing the text {@link workspaceStatus} would produce.
- * @param counts - Counts from {@link workspaceCounts}.
- * @param style - `words` spells each state out; `badges` keeps only the marker and the count.
- * @returns The cells in the order given, with their separators.
- */
-export declare function workspaceSegments(counts: readonly RollupCount[], style?: RollupStyle): {
-    state: RollupState;
-    text: string;
-}[];
-/** Render one rollup as plain text, the same way every screen and test reads it.
- * @param counts - Counts from {@link workspaceCounts}.
- * @param style - `words` spells each state out; `badges` keeps only the marker and the count.
- * @returns The joined cell text, empty when nothing was counted.
- */
-export declare function workspaceStatus(counts: readonly RollupCount[], style?: RollupStyle): string;
-/** Marker key for the compact rollup, which has no room for the words. */
-export declare const ROLLUP_LEGEND: string;
-/** Secondary path text for one workspace row.
- *
- * The title is usually the last path segment, so repeating it wastes the row; the parent directory
- * is what distinguishes two checkouts. A title that does not name the last segment keeps the full
- * path, because dropping it would hide where the workspace actually lives.
- * @param path - Registered host directory.
- * @param title - Workspace title as the row already shows it.
- * @returns The path to show beside the row, or an empty string when nothing is left.
- */
-export declare function workspaceDetail(path: string, title: string): string;