@sagentlab/navarch-runtime 0.1.112 → 0.1.117

package/node_modules/@muse-code/sdk/dist/src/facade/turn-handle.d.ts

@@ -0,0 +1,156 @@
+/**
+ * `TurnHandle` — one turn's view of the fold (spec 14990 FR-018, INV-014;
+ * tasks.md T030).
+ *
+ * A handle owns two things: the SS3.1.4 turn-wait, and the async iterators
+ * that ride the fold for this turn. It authors no wire traffic and holds no
+ * durable state — `Session` feeds it folded events and it fans them out.
+ *
+ * INV-006 governs the wait: the SDK never locally times out, fails, or
+ * completes a turn. Every settlement below traces to a server-authored fact,
+ * with one sanctioned exception that is not a terminal at all —
+ * terminal-unknown after an ephemeral host death, which SS2.13.3b makes a
+ * client MUST ("stop waiting for a terminal") and which stays an annotation
+ * rather than a synthesized event.
+ */
+import type { Item, ItemDeltaParams, TurnCompletedParams, TurnUnqueuedParams } from "../msp.js";
+import type { DeepReadonly } from "../fold/session-fold.js";
+/**
+ * What the iterators yield: the fold's stored item, sealed.
+ *
+ * `DeepReadonly` because these ARE the objects the fold holds — the generated
+ * wire types carry no `readonly`, so an unsealed yield would let a consumer
+ * write `item.revision = 0` and defeat the INV-003 guard through the read
+ * surface (PR #23087 review round). The seal is compile-time only; nothing is
+ * frozen or cloned on the hot path.
+ */
+export type FoldedItem = DeepReadonly<Item>;
+/**
+ * How a turn ended, from a waiter's point of view.
+ *
+ * SS3.1.4 names exactly two resolutions of the turn-wait, and the pre-minted
+ * turn is why there are two rather than one:
+ *
+ *  - `completed` — the ordinary terminal, AND the launch-failure exit
+ *    (`"deferred_start_failed"`: terminal `"failed"`, `error.kind:
+ *    "launchError"`, no preceding `turn/started`). `isLaunchFailure` reads
+ *    that WIRE marker; `observedStart` does not discriminate them, because a
+ *    terminal-first fold is legitimate for turns that really ran.
+ *  - `unqueued` — the reclaim (SS3.6). No `turn/completed` will ever carry
+ *    this `turnId`, so a wait folding only `turn/completed` hangs forever.
+ *
+ * `turn/retracted` and `turn/retryScheduled` are deliberately absent: a
+ * retracted turn still reaches its own terminal, and a scheduled retry is
+ * explicitly non-terminal (SS4.5.1).
+ */
+export type TurnOutcome = {
+    readonly kind: "completed";
+    readonly params: TurnCompletedParams;
+    /**
+     * Did THIS session observe a `turn/started` for this turn?
+     *
+     * A session-local observation, NOT a launch-failure marker. The fold
+     * deliberately accepts a terminal-first `turn/completed` for turns that
+     * really did run — single-shot turns, gap fills, and any consumer that
+     * attached mid-stream or replayed a canned transcript from partway
+     * through — so `false` here covers those too.
+     *
+     * The launch failure has its own WIRE marker and that is the one to
+     * branch on: `terminal: "failed"` with `error.kind: "launchError"`
+     * (tdd SS3.1.4/SS4.5.1). `isLaunchFailure` below reads it.
+     */
+    readonly observedStart: boolean;
+} | {
+    readonly kind: "unqueued";
+    readonly params: TurnUnqueuedParams;
+}
+/**
+ * SS2.13.3b: an ephemeral host died, so the client stops waiting. Carries no
+ * `reason`: the arm has exactly one cause, so a single-valued field would
+ * add nothing `kind` does not already say while freezing a permanent
+ * obligation into a public type (Constitution XI).
+ */
+ | {
+    readonly kind: "terminalUnknown";
+};
+/**
+ * The `"deferred_start_failed"` exit (SS3.1.4/SS3.2): a pre-minted turn whose
+ * launch errored at the terminal boundary, so the runtime wrote its terminal
+ * directly and no `turn/started` was ever emitted BY THE HOST.
+ *
+ * Read off the wire, never off local observation: a client that had not been
+ * listening when the turn started is not looking at a launch failure.
+ */
+export declare function isLaunchFailure(outcome: TurnOutcome): boolean;
+/** The turn's replayable backlog, supplied by `Session` from the fold. */
+export type ItemReplay = () => readonly FoldedItem[];
+/**
+ * A turn, as a CONSUMER sees it — the SS7.1 turn surface and nothing else.
+ *
+ * `Session.turn()` returns this rather than the concrete `TurnHandle` because
+ * the handle's "fed by Session" mutators (`settleCompleted`, `settleUnqueued`,
+ * `fail`, `pushItem`, …) would otherwise be public: an embedder could call
+ * `settleCompleted` and fabricate a terminal the server never authored, which
+ * is exactly what INV-006 forbids. They stay reachable only through
+ * `Session.apply`, i.e. only from a server-authored event.
+ */
+export interface Turn {
+    readonly turnId: string;
+    /** Did THIS session observe a `turn/started`? Not a launch-failure marker. */
+    readonly observedStart: boolean;
+    readonly completed: Promise<TurnOutcome>;
+    items(): AsyncIterableIterator<FoldedItem>;
+    deltas(): AsyncIterableIterator<ItemDeltaParams>;
+}
+export declare class TurnHandle implements Turn {
+    #private;
+    readonly turnId: string;
+    constructor(turnId: string, replayItems: ItemReplay);
+    /** Settles on `turn/completed`, `turn/unqueued`, or the ephemeral discard. */
+    get completed(): Promise<TurnOutcome>;
+    /**
+     * How many iterators this handle is still fanning out to.
+     *
+     * Exposed so the deregistration contract is assertable: an iterator a
+     * consumer broke out of, or simply dropped, must leave this set rather than
+     * accumulate for the rest of the turn.
+     */
+    get liveStreamCount(): number;
+    /** Did a `turn/started` ever fold for this turn? */
+    get observedStart(): boolean;
+    /**
+     * This turn's items: everything the fold already holds for it, at its
+     * current revision and in first-opened order, then the live tail — one yield
+     * per fold-observed revision CHANGE. A stale re-emission mutates nothing
+     * (INV-003) and therefore yields nothing.
+     *
+     * The iterator ends when the turn settles; it never ends on a local timeout.
+     */
+    items(): AsyncIterableIterator<FoldedItem>;
+    /**
+     * This turn's `item/delta` frames, live only.
+     *
+     * Deliberately NOT replayed, and the asymmetry with `items()` is a fact
+     * about the fold rather than an oversight: the store holds each item at its
+     * latest revision plus the ACCUMULATED delta text per field path
+     * (`ItemStore.accumulated`), never the delta event sequence. A consumer
+     * attaching mid-turn reads the accumulated value from the fold; there is no
+     * retained event list to replay, and inventing one would be a second copy of
+     * state that INV-002's determinism would then have to defend.
+     */
+    deltas(): AsyncIterableIterator<ItemDeltaParams>;
+    markStarted(): void;
+    pushItem(item: FoldedItem): void;
+    pushDelta(params: ItemDeltaParams): void;
+    settleCompleted(params: TurnCompletedParams): void;
+    settleUnqueued(params: TurnUnqueuedParams): void;
+    /** SS2.13.3b: an ephemeral host died; stop waiting for a terminal. */
+    settleTerminalUnknown(): void;
+    /**
+     * A DURABLE host died abnormally. The waiter gets no answer here — FM-001
+     * puts the terminals on resume — so it is rejected rather than resolved: a
+     * resolution would be the invented terminal INV-006 forbids, and silence
+     * would be the SS3.1.4 hang.
+     */
+    fail(error: unknown): void;
+}

package/node_modules/@muse-code/sdk/dist/src/facade/turn-handle.js

@@ -0,0 +1,271 @@
+/**
+ * `TurnHandle` — one turn's view of the fold (spec 14990 FR-018, INV-014;
+ * tasks.md T030).
+ *
+ * A handle owns two things: the SS3.1.4 turn-wait, and the async iterators
+ * that ride the fold for this turn. It authors no wire traffic and holds no
+ * durable state — `Session` feeds it folded events and it fans them out.
+ *
+ * INV-006 governs the wait: the SDK never locally times out, fails, or
+ * completes a turn. Every settlement below traces to a server-authored fact,
+ * with one sanctioned exception that is not a terminal at all —
+ * terminal-unknown after an ephemeral host death, which SS2.13.3b makes a
+ * client MUST ("stop waiting for a terminal") and which stays an annotation
+ * rather than a synthesized event.
+ */
+/**
+ * Bound through the CLOSED extraction of each generated vocabulary. Both
+ * `TurnTerminal` and `TurnErrorKind` end in `| (string & {})`, so a bare
+ * `"launchEror"` compiles green against them — and this discriminator is
+ * barrel-exported, so the typo would ship. Every sibling literal in this
+ * package is bound the same way for the same reason.
+ */
+const TERMINAL_FAILED = "failed";
+const LAUNCH_ERROR = "launchError";
+/**
+ * The `"deferred_start_failed"` exit (SS3.1.4/SS3.2): a pre-minted turn whose
+ * launch errored at the terminal boundary, so the runtime wrote its terminal
+ * directly and no `turn/started` was ever emitted BY THE HOST.
+ *
+ * Read off the wire, never off local observation: a client that had not been
+ * listening when the turn started is not looking at a launch failure.
+ */
+export function isLaunchFailure(outcome) {
+    return (outcome.kind === "completed" &&
+        outcome.params.terminal === TERMINAL_FAILED &&
+        outcome.params.error?.kind === LAUNCH_ERROR);
+}
+/**
+ * A single-consumer push stream. Buffers when nobody is awaiting and hands the
+ * buffer over before reporting an end or a failure, so a consumer never loses
+ * events it was already owed.
+ */
+class PushStream {
+    #buffer = [];
+    #onFinished;
+    /**
+     * FIFO, not a single slot. `items()`/`deltas()` hand out a plain
+     * `AsyncIterableIterator`, so `Promise.all([it.next(), it.next()])` prefetch
+     * is a reasonable thing for a consumer to write — and a single slot let the
+     * second call overwrite the first waiter, leaving the first promise never
+     * settled and handing its value to the second caller. A silently
+     * never-settling promise is the hang class this file exists to prevent.
+     */
+    #waiters = [];
+    #ended = false;
+    #failure;
+    /**
+     * `onFinished` deregisters this stream from its owner. Without it a consumer
+     * that `break`s out of a `for await` — or simply drops the iterator — stays
+     * in the fan-out set for the rest of the turn, so every later event is
+     * pushed into a stream nobody reads. A render loop that re-attaches per
+     * frame would grow one dead stream per frame.
+     */
+    constructor(onFinished) {
+        this.#onFinished = onFinished;
+    }
+    push(value) {
+        if (this.#ended)
+            return;
+        const waiter = this.#waiters.shift();
+        if (waiter === undefined) {
+            this.#buffer.push(value);
+            return;
+        }
+        waiter.resolve({ done: false, value });
+    }
+    end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        // Drain EVERY queued waiter, not just the oldest.
+        for (const waiter of this.#waiters.splice(0)) {
+            waiter.resolve({ done: true, value: undefined });
+        }
+    }
+    fail(error) {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        this.#failure = error;
+        for (const waiter of this.#waiters.splice(0))
+            waiter.reject(error);
+    }
+    next() {
+        // Buffered values come out first even after an end or a failure: the
+        // consumer was already owed them, and swallowing them here would be the
+        // silent hole the iterators exist to prevent.
+        if (this.#buffer.length > 0) {
+            return Promise.resolve({ done: false, value: this.#buffer.shift() });
+        }
+        if (this.#failure !== undefined)
+            return Promise.reject(this.#failure);
+        if (this.#ended)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve, reject) => {
+            this.#waiters.push({ reject, resolve });
+        });
+    }
+    /** `break`/`return` inside a `for await`: drop the backlog and finish. */
+    return() {
+        this.#buffer.length = 0;
+        this.end();
+        this.#onFinished();
+        return Promise.resolve({ done: true, value: undefined });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+export class TurnHandle {
+    turnId;
+    #replayItems;
+    #itemStreams = new Set();
+    #deltaStreams = new Set();
+    #completed;
+    #settle;
+    #fail;
+    #observedStart = false;
+    #settled = false;
+    /**
+     * Retained so an iterator opened AFTER the failure reports it too. Without
+     * it a late `items()` saw only `#settled` and ended cleanly — handing the
+     * consumer a partial replay plus a tidy `done`, i.e. an unfinished turn
+     * rendered as finished, which is the invented completion INV-006 forbids.
+     */
+    #failure;
+    constructor(turnId, replayItems) {
+        this.turnId = turnId;
+        this.#replayItems = replayItems;
+        this.#completed = new Promise((resolve, reject) => {
+            this.#settle = resolve;
+            this.#fail = reject;
+        });
+        // A wait nobody awaits must not crash the embedding host on rejection.
+        // Later awaiters still receive it (the same posture `MuseServeChild` takes).
+        this.#completed.catch(() => { });
+    }
+    /** Settles on `turn/completed`, `turn/unqueued`, or the ephemeral discard. */
+    get completed() {
+        return this.#completed;
+    }
+    /**
+     * How many iterators this handle is still fanning out to.
+     *
+     * Exposed so the deregistration contract is assertable: an iterator a
+     * consumer broke out of, or simply dropped, must leave this set rather than
+     * accumulate for the rest of the turn.
+     */
+    get liveStreamCount() {
+        return this.#itemStreams.size + this.#deltaStreams.size;
+    }
+    /** Did a `turn/started` ever fold for this turn? */
+    get observedStart() {
+        return this.#observedStart;
+    }
+    /**
+     * This turn's items: everything the fold already holds for it, at its
+     * current revision and in first-opened order, then the live tail — one yield
+     * per fold-observed revision CHANGE. A stale re-emission mutates nothing
+     * (INV-003) and therefore yields nothing.
+     *
+     * The iterator ends when the turn settles; it never ends on a local timeout.
+     */
+    items() {
+        const stream = new PushStream(() => this.#itemStreams.delete(stream));
+        for (const item of this.#replayItems())
+            stream.push(item);
+        this.#admit(stream, this.#itemStreams);
+        return stream;
+    }
+    /**
+     * This turn's `item/delta` frames, live only.
+     *
+     * Deliberately NOT replayed, and the asymmetry with `items()` is a fact
+     * about the fold rather than an oversight: the store holds each item at its
+     * latest revision plus the ACCUMULATED delta text per field path
+     * (`ItemStore.accumulated`), never the delta event sequence. A consumer
+     * attaching mid-turn reads the accumulated value from the fold; there is no
+     * retained event list to replay, and inventing one would be a second copy of
+     * state that INV-002's determinism would then have to defend.
+     */
+    deltas() {
+        const stream = new PushStream(() => this.#deltaStreams.delete(stream));
+        this.#admit(stream, this.#deltaStreams);
+        return stream;
+    }
+    /**
+     * Register a fresh stream, or finish it the way this turn already finished.
+     * The failure branch comes FIRST: a turn that failed is not a turn that
+     * ended. `PushStream` drains the replay before reporting either, so a late
+     * consumer still receives everything it was owed.
+     */
+    #admit(stream, into) {
+        if (this.#failure !== undefined)
+            stream.fail(this.#failure);
+        else if (this.#settled)
+            stream.end();
+        else
+            into.add(stream);
+    }
+    // ---- fed by Session -----------------------------------------------------
+    markStarted() {
+        this.#observedStart = true;
+    }
+    pushItem(item) {
+        for (const stream of this.#itemStreams)
+            stream.push(item);
+    }
+    pushDelta(params) {
+        for (const stream of this.#deltaStreams)
+            stream.push(params);
+    }
+    settleCompleted(params) {
+        this.#finish({ kind: "completed", observedStart: this.#observedStart, params });
+    }
+    settleUnqueued(params) {
+        this.#finish({ kind: "unqueued", params });
+    }
+    /** SS2.13.3b: an ephemeral host died; stop waiting for a terminal. */
+    settleTerminalUnknown() {
+        this.#finish({ kind: "terminalUnknown" });
+    }
+    /**
+     * A DURABLE host died abnormally. The waiter gets no answer here — FM-001
+     * puts the terminals on resume — so it is rejected rather than resolved: a
+     * resolution would be the invented terminal INV-006 forbids, and silence
+     * would be the SS3.1.4 hang.
+     */
+    fail(error) {
+        if (this.#settled)
+            return;
+        this.#settled = true;
+        this.#failure = error;
+        this.#fail?.(error);
+        this.#clear();
+        for (const stream of this.#itemStreams)
+            stream.fail(error);
+        for (const stream of this.#deltaStreams)
+            stream.fail(error);
+        this.#itemStreams.clear();
+        this.#deltaStreams.clear();
+    }
+    #finish(outcome) {
+        // First settlement wins: a duplicate terminal is a losing racer's echo.
+        if (this.#settled)
+            return;
+        this.#settled = true;
+        this.#settle?.(outcome);
+        this.#clear();
+        for (const stream of this.#itemStreams)
+            stream.end();
+        for (const stream of this.#deltaStreams)
+            stream.end();
+        this.#itemStreams.clear();
+        this.#deltaStreams.clear();
+    }
+    #clear() {
+        this.#settle = undefined;
+        this.#fail = undefined;
+    }
+}

package/node_modules/@muse-code/sdk/dist/src/facade/turn-submit.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `turn/start` submission and same-`commandId` replay (spec 14990 FR-018 /
+ * T030 obligations (a) and (d); tdd SS3.1.1, SS3.2, SS4.13).
+ *
+ * Split out of `session.ts` for the same reason `approval.ts` was: this is a
+ * wire-shaping and idempotency concern, not a fold concern, and `Session` was
+ * already the package's largest module.
+ *
+ * It holds the ONE piece of state `PendingCommandSet` deliberately cannot: the
+ * `turn/start` params per `commandId`. The set stores the COMPOSER input and is
+ * wire-blind by design (INV-001), so a replay — which must re-send the SAME
+ * logical command, byte for byte, to be the sanctioned retry rather than a
+ * double execution — needs the params to live on this side of that boundary.
+ */
+import type { Connection } from "../connection/connection.js";
+import type { PendingCommandSet } from "../pending/pending-command-set.js";
+import type { CommandErrorResponse, PendingCommandAck, PendingRetirement, ReplayAnswer } from "../pending/pending-command-set.js";
+import type { TurnStartParams } from "../msp.js";
+/**
+ * What `Session.sendUserTurn` sends, COMPOSED from the generated params rather
+ * than restated (INV-001).
+ *
+ * `commandId` is excluded because `Connection` is the single minter (INV-013);
+ * `sessionId` because the session already knows its own and a caller-supplied
+ * one could only disagree with it.
+ */
+export type SendUserTurnOptions<I> = Readonly<Omit<TurnStartParams, "commandId" | "sessionId">> & {
+    /**
+     * What to hand back to the composer if this submit is ever retired — SS4.13
+     * restores the INPUT, not the wire parts. Optional: a consumer that renders
+     * nothing optimistically has nothing to restore.
+     */
+    readonly composerInput?: I;
+};
+/**
+ * An `MspError` as the pending set reads it (SS4.13's settlement test).
+ *
+ * `undefined` for anything that is NOT a server-authored MSP error — a
+ * `ProtocolError`, a dead transport — because those admit nothing AND prove
+ * nothing about the intake, so the entry must HOLD rather than be judged.
+ */
+export declare function commandErrorResponse(error: unknown): CommandErrorResponse | undefined;
+export declare class TurnSubmitter<I> {
+    #private;
+    constructor(sessionId: string, connection: Connection | undefined, pending: PendingCommandSet<I>);
+    get wired(): boolean;
+    requireConnection(verb: string): Connection;
+    /**
+     * Record the optimistic SS4.13 entry, then send `turn/start`.
+     *
+     * The ORDER is the point. An entry created only on the ack is invisible for
+     * exactly the window it exists to cover — between the user pressing enter and
+     * the host answering — and `anchorAfterItemId` is fixed here, at submission
+     * time, because SS4.13's insertion point may never be relocated by events
+     * that fold in afterwards.
+     */
+    submit(options: SendUserTurnOptions<I>, anchorAfterItemId: string | null): Promise<PendingCommandAck>;
+    /**
+     * Re-send one remembered `turn/start` under its ORIGINAL `commandId`
+     * (SS3.1.1 — always safe, and the only re-send that is not a double
+     * execution).
+     *
+     * `undefined` means "no answer this set can act on": either this session
+     * never authored the command (a caller-seeded entry), or the failure was a
+     * transport/protocol one, which proves nothing about the intake.
+     */
+    replay(commandId: string): Promise<ReplayAnswer | undefined>;
+    /** Replay one entry and feed the answer back through the live SS4.13 rules. */
+    driveReplay(commandId: string, into: PendingRetirement<I>[]): Promise<void>;
+    /** Drop the replay memory for retired entries so it tracks the pending set. */
+    forgetRetired(retirements: readonly PendingRetirement<I>[]): void;
+}

package/node_modules/@muse-code/sdk/dist/src/facade/turn-submit.js

@@ -0,0 +1,183 @@
+/**
+ * `turn/start` submission and same-`commandId` replay (spec 14990 FR-018 /
+ * T030 obligations (a) and (d); tdd SS3.1.1, SS3.2, SS4.13).
+ *
+ * Split out of `session.ts` for the same reason `approval.ts` was: this is a
+ * wire-shaping and idempotency concern, not a fold concern, and `Session` was
+ * already the package's largest module.
+ *
+ * It holds the ONE piece of state `PendingCommandSet` deliberately cannot: the
+ * `turn/start` params per `commandId`. The set stores the COMPOSER input and is
+ * wire-blind by design (INV-001), so a replay — which must re-send the SAME
+ * logical command, byte for byte, to be the sanctioned retry rather than a
+ * double execution — needs the params to live on this side of that boundary.
+ */
+import { MspError } from "../connection/connection.js";
+/**
+ * Every member forwarded to the wire. Composition alone does not stop drift —
+ * the guard chain in `#params` is hand-listed — so a regenerated member fails
+ * the BUILD here until it is forwarded.
+ */
+const TURN_START_FORWARDED = [
+    "input",
+    "displayText",
+    "ifBusy",
+    "reasoningEffort",
+    // No "tokenBudget" (#45454): experimental-gated, and this SDK serves the
+    // stable surface only.
+    "workspaceRoots",
+    // v1 stable member, forwarded like any other.
+    "userShell",
+];
+/**
+ * An `MspError` as the pending set reads it (SS4.13's settlement test).
+ *
+ * `undefined` for anything that is NOT a server-authored MSP error — a
+ * `ProtocolError`, a dead transport — because those admit nothing AND prove
+ * nothing about the intake, so the entry must HOLD rather than be judged.
+ */
+export function commandErrorResponse(error) {
+    if (!(error instanceof MspError))
+        return undefined;
+    const reason = error.data["reason"];
+    return {
+        code: error.code,
+        kind: error.kind,
+        ...(typeof reason === "string" ? { reason } : {}),
+    };
+}
+export class TurnSubmitter {
+    #sessionId;
+    #connection;
+    #pending;
+    /** See the module doc. Pruned on retirement, so it tracks the pending set. */
+    #memory = new Map();
+    constructor(sessionId, connection, pending) {
+        this.#sessionId = sessionId;
+        this.#connection = connection;
+        this.#pending = pending;
+    }
+    get wired() {
+        return this.#connection !== undefined;
+    }
+    requireConnection(verb) {
+        const connection = this.#connection;
+        if (connection === undefined) {
+            // A plain `Error`: calling a submit verb on a fold-only Session is API
+            // misuse, not the foreign-frame STATE `MuseForeignSessionError` names.
+            throw new Error(`${verb} needs a connection; this Session was constructed fold-only`);
+        }
+        return connection;
+    }
+    /**
+     * Record the optimistic SS4.13 entry, then send `turn/start`.
+     *
+     * The ORDER is the point. An entry created only on the ack is invisible for
+     * exactly the window it exists to cover — between the user pressing enter and
+     * the host answering — and `anchorAfterItemId` is fixed here, at submission
+     * time, because SS4.13's insertion point may never be relocated by events
+     * that fold in afterwards.
+     */
+    async submit(options, anchorAfterItemId) {
+        const connection = this.requireConnection("sendUserTurn");
+        // Delegated, not re-implemented: the connection owns the single mint, so
+        // INV-013's single-minter property survives this verb needing the id early.
+        const commandId = connection.mintCommandId();
+        const params = this.#params(commandId, options);
+        this.#pending.submitted({
+            anchorAfterItemId,
+            commandId,
+            input: options.composerInput,
+            ...(params.displayText === undefined ? {} : { displayText: params.displayText }),
+        });
+        this.#memory.set(commandId, params);
+        try {
+            const ack = await this.#send(connection, params, commandId);
+            this.#pending.acked(commandId, ack);
+            return ack;
+        }
+        catch (error) {
+            const response = commandErrorResponse(error);
+            // Only a durable -32030 settles; every other error admitted nothing and
+            // the entry HOLDS for the caller's same-commandId retry (SS4.13).
+            if (response !== undefined) {
+                const settled = this.#pending.ackErrored(commandId, response);
+                if (settled !== "held")
+                    this.forgetRetired([settled]);
+            }
+            // Rethrown, deliberately: the caller who submitted still holds its own
+            // input, so this path needs no second retirement channel.
+            throw error;
+        }
+    }
+    /**
+     * Re-send one remembered `turn/start` under its ORIGINAL `commandId`
+     * (SS3.1.1 — always safe, and the only re-send that is not a double
+     * execution).
+     *
+     * `undefined` means "no answer this set can act on": either this session
+     * never authored the command (a caller-seeded entry), or the failure was a
+     * transport/protocol one, which proves nothing about the intake.
+     */
+    async replay(commandId) {
+        const params = this.#memory.get(commandId);
+        if (params === undefined)
+            return undefined;
+        const connection = this.requireConnection("turn/start replay");
+        try {
+            return { ack: await this.#send(connection, params, commandId), kind: "ack" };
+        }
+        catch (error) {
+            const response = commandErrorResponse(error);
+            if (response === undefined)
+                return undefined;
+            return { error: response, kind: "error" };
+        }
+    }
+    /** Replay one entry and feed the answer back through the live SS4.13 rules. */
+    async driveReplay(commandId, into) {
+        const answer = await this.replay(commandId);
+        if (answer === undefined)
+            return;
+        const settled = this.#pending.replayAnswered(commandId, answer);
+        if (settled !== "held")
+            into.push(settled);
+    }
+    /** Drop the replay memory for retired entries so it tracks the pending set. */
+    forgetRetired(retirements) {
+        for (const retirement of retirements)
+            this.#memory.delete(retirement.commandId);
+    }
+    async #send(connection, params, commandId) {
+        const raw = await connection.command("turn/start", params, { commandId });
+        const result = raw;
+        // `turnId` comes from the ACK and never from the `commandId`: SS3.2 makes
+        // the ack authoritative, and a queued submit's turn may already exist.
+        return { disposition: result.disposition, turnId: result.turnId };
+    }
+    /**
+     * OPTIONAL MEANS OMITTED, NEVER `null` (tdd SS1.2), and the guards are LOOSE
+     * (`!= null`) for the same reason `MuseClient`'s are: the types bind only
+     * strict TypeScript consumers, and a plain-JS caller reaching the built
+     * `dist` can pass an explicit `null` a `!== undefined` guard would forward.
+     */
+    #params(commandId, options) {
+        const params = {
+            commandId,
+            input: options.input,
+            sessionId: this.#sessionId,
+        };
+        if (options.displayText != null)
+            params.displayText = options.displayText;
+        if (options.ifBusy != null)
+            params.ifBusy = options.ifBusy;
+        if (options.reasoningEffort != null)
+            params.reasoningEffort = options.reasoningEffort;
+        // No tokenBudget forward (#45454): experimental-gated, stable SDK omits it.
+        if (options.workspaceRoots != null)
+            params.workspaceRoots = options.workspaceRoots;
+        if (options.userShell != null)
+            params.userShell = options.userShell;
+        return params;
+    }
+}