@kortix/sdk 0.12.8 → 0.13.1

package/dist/react/use-session.js

@@ -1,44 +1,27 @@
 'use client';
-/**
- * useSession — the ONE hook a host needs to open a session and stream a chat.
- *
- * Everything sandbox-shaped is internal: it drives `/start` (server long-poll),
- * points the runtime at the session's sandbox, opens the SSE stream, resolves the
- * canonical OpenCode id, and syncs messages — exposing one `phase`
- * (starting|ready|error) plus messages/send/abort/questions/permissions and the
- * server-side capabilities (models/agents/commands/picks). The host imports
- * `createKortix` + `useSession` and NOTHING else runtime-related: no server-store,
- * no `switchToSessionSandboxAsync`, no health poller, no event-stream provider.
- *
- * Readiness comes from the SERVER (`stage==='ready'` is only returned after the
- * daemon answered), seeded into the connection store on switch — so there is NO
- * client health poller, and the first turn streams immediately.
- *
- * Call this ONCE per session view (like a provider): it owns the SSE subscription
- * and the `/start` poll for `(projectId, sessionId)`.
- */
 import { useQuery, useQueryClient } from '@tanstack/react-query';
-import { useEffect, useMemo, useRef, useState } from 'react';
-import { beginSessionPromptObservation, endSessionPromptObservation, } from '../browser/session-sync/session-sync-registry.js';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useOpenCodeCompactionStore } from '../browser/stores/opencode-compaction-store.js';
+import { useSessionWorkingStore } from '../browser/stores/session-working-store.js';
+import { compactionExpiryAtMs, projectCompacting, serverCompactionRevalidateAtMs, } from '../core/session/compaction.js';
 import { useOpenCodePendingStore } from '../browser/stores/opencode-pending-store.js';
-import { setOpenCodeHealth, setSandboxStatus } from '../browser/stores/sandbox-connection-store.js';
+import { markRuntimeReadyVerified, setOpenCodeHealth, setSandboxStatus, } from '../browser/stores/sandbox-connection-store.js';
 import { getSandboxUrlForExternalId } from '../browser/stores/server-store.js';
-import { useSyncStore } from '../browser/stores/sync-store.js';
+import { ascendingId, useSyncStore } from '../browser/stores/sync-store.js';
 import { BillingError, parseBillingError } from '../core/http/api/errors.js';
 import { isSessionFresh } from '../core/http/fresh-sessions.js';
 import { formatOpenCodeRuntimeError } from '../core/http/opencode-errors.js';
 import { isSessionStartError, sessionStartKey, startProjectSession, } from '../core/rest/projects-client/index.js';
 import { RuntimeNotReadyError, getClient } from '../core/runtime/client.js';
 import { setCurrentRuntime } from '../core/session/current-runtime.js';
-import { commitSessionRewind, messagesBeforeRewind, reconcileCommittedSessionRewind, } from '../core/session/rewind.js';
+import { messagesBeforeRewind } from '../core/session/rewind.js';
 import { extractGatewayErrorDetails } from '../core/turns/errors.js';
 import { clearStartStash, readStartStash } from './session-start-stash.js';
 import { reconcileHydratedSessionTitle } from './session-title-sync.js';
 import { useCanonicalOpenCodeSession } from './use-canonical-opencode-session.js';
 import { useOpenCodeEventStream } from './use-opencode-events/index.js';
 import { formatModelString } from './use-opencode-local.js';
-import { rejectQuestion as rejectQuestionApi, replyToPermission, replyToQuestion, useAbortOpenCodeSession, useExecuteOpenCodeCommand, useSendOpenCodeMessage, } from './use-opencode-sessions/index.js';
+import { abortInFlightDeliveries, awaitAbortSettlement, opencodeKeys, rejectQuestion as rejectQuestionApi, replyToPermission, replyToQuestion, useAbortOpenCodeSession, useExecuteOpenCodeCommand, useOpenCodeSession, useSendOpenCodeMessage, } from './use-opencode-sessions/index.js';
 import { unwrap } from './use-opencode-sessions/shared.js';
 import { usePermissionSelfHeal } from './use-permission-self-heal.js';
 import { useProjectConfig } from './use-project-config.js';
@@ -48,7 +31,14 @@ import { useRuntimePhase } from './use-runtime-phase.js';
 import { useSessionPicks } from './use-session-picks.js';
 import { derivePhase } from './use-session-phase.js';
 import { useSessionSync } from './use-session-sync.js';
+import { useSessionWorking } from './use-session-working.js';
 import { useVisibleAgents } from './use-visible-agents.js';
+// `useLayoutEffect` warns during SSR ("useLayoutEffect does nothing on the
+// server"). This file is always `'use client'`, but Next.js still runs an
+// initial SSR pass before hydration — fall back to `useEffect` there. See the
+// mount-time `markRuntimeReadyVerified` seed below for why this hook needs a
+// LAYOUT effect specifically (ordering, not paint timing).
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 // Grace window for the optimistic create-vs-start race: how long /start keeps
 // retrying a 404 for a freshly-minted session before treating it as terminal.
 // ~12 × 800ms ≈ 9.6s, comfortably past the sub-second create POST.
@@ -211,6 +201,63 @@ export function computeStartSettled(input) {
         return false;
     return !shouldPollSessionStart(input.error, input.data);
 }
+/**
+ * How long a `ready` /start result stays fresh enough that a REMOUNT renders
+ * it straight from the TanStack Query cache with zero network `/start` before
+ * first paint — the "user just left this exact session and came right back"
+ * case (tab switch, back button, re-opening the same session from the
+ * project's session list), which otherwise re-POSTs `/start` (and re-waits
+ * its up-to-`waitMs` server long-poll) on every single mount even though the
+ * box never went anywhere.
+ *
+ * The server parks an idle sandbox after ~15 minutes (see the `/start` route
+ * this hook drives, in `session-sandbox.ts`), so this window is nowhere near
+ * long enough to promise anything about a sandbox that has genuinely been
+ * idle — it only needs to outlast the sub-second "switch thrash" case, not
+ * survive a real absence. 30s comfortably covers that without risking a
+ * materially stale "ready" read surviving into a box the server already
+ * parked: `sessionStartStaleTime` only skips the IMMEDIATE refetch, it never
+ * cancels one — a background refetch still fires once the cached entry ages
+ * past this window (stale-while-revalidate), so a parked box still converges
+ * to `stopped` on the very next look.
+ */
+export const SESSION_START_FRESH_MS = 30_000;
+/**
+ * OUTCOME-AWARE `staleTime` for the `/start` query (TanStack's function
+ * form). Only a `stage==='ready'` result may be served from cache without an
+ * immediate refetch — every other stage (`provisioning`/`starting`/
+ * `stopped`/`failed`, or no cached data yet) represents an in-flight or
+ * terminal state that must keep converging on server truth, so it stays
+ * maximally stale (`0`, i.e. TanStack's "always refetch on mount") —
+ * unchanged from this query's behavior before this staleTime existed.
+ *
+ * This does NOT change `refetchInterval` (`SESSION_START_POLL_OPTIONS`,
+ * below, untouched): a `ready` result already stops that poll
+ * (`shouldPollSessionStart`), so this only governs remount behavior, never
+ * steady-state polling.
+ */
+export function sessionStartStaleTime(query) {
+    return query.state.data?.stage === 'ready' ? SESSION_START_FRESH_MS : 0;
+}
+/**
+ * Whether a cached `/start` query STATE (as sitting in the TanStack Query
+ * cache the moment a session starts mounting) already says `stage==='ready'`
+ * — independent of staleness/age: React Query serves whatever is cached
+ * synchronously on every mount regardless of `staleTime` (`staleTime` only
+ * gates whether a background refetch ALSO fires, never whether the cached
+ * data renders) — so a session left seconds or minutes ago can make
+ * `switched` true well before this mount's own effects have a chance to run.
+ *
+ * Pure so the mount-time `markRuntimeReadyVerified()` decision it feeds (the
+ * `useIsomorphicLayoutEffect` in {@link useSession}, right after the /start
+ * query below) is unit-testable without rendering the hook — this package has
+ * no hook-render harness, so pure predicates like this ARE the test surface
+ * for effect-gated logic (see `computeStartSettled`/`nextInconclusiveSince`
+ * above for the established pattern).
+ */
+export function cachedStartResultIsReady(cachedState) {
+    return cachedState?.data?.stage === 'ready';
+}
 /**
  * TanStack Query pauses interval fetches while the document is hidden unless
  * this option is true. Session readiness must continue because it gates the
@@ -238,7 +285,7 @@ const RUNTIME_NOT_READY_MARKER = 'Server URL not ready';
  *
  * A no-op when the parts carry no ids or belong to no optimistic message.
  */
-function markDispatchedForPartIds(sessionId, parts) {
+export function markDispatchedForPartIds(sessionId, parts) {
     const partIds = new Set(parts
         .map((p) => p.id)
         .filter((id) => typeof id === 'string' && !!id));
@@ -253,6 +300,60 @@ function markDispatchedForPartIds(sessionId, parts) {
             store.markOptimisticDispatched(sessionId, message.id);
     }
 }
+/**
+ * Optimistically add the user's message for a plain-text `send()` call, and
+ * mint the SAME part id onto both the optimistic part AND the outgoing wire
+ * part `send()` goes on to POST.
+ *
+ * T15 — "one user bubble": `send()` used to build its outgoing part
+ * as `{ type: 'text', text }` with no id at all, so — even where a host paired
+ * it with its own optimistic add — nothing correlated the two. The sync
+ * store's `message.updated` handler matches an incoming echo to an optimistic
+ * message primarily by EXACT part id (opencode preserves a client-supplied
+ * part id on echo); only when that fails does it fall back to "the oldest
+ * DISPATCHED optimistic message" (`markDispatchedForPartIds`, called
+ * unconditionally by `sendParts` below, marks it — but only once the part ids
+ * actually match, same root cause). With no id on the wire, neither path can
+ * ever fire, and the user's text stayed doubled on screen until the next
+ * idle sweep (`clearOptimisticMessages`).
+ *
+ * Mirrors `beginOptimisticSend` (`use-session-send.ts`) exactly — same store
+ * calls, same stub-message shape, same "skip parts for empty/whitespace text"
+ * rule — kept as a sibling here rather than imported, since
+ * `use-session-send.ts` already imports FROM this module (`classifySendError`)
+ * and a reverse import would make the two files mutually dependent.
+ */
+export function beginOptimisticPlainTextSend(sessionId, text) {
+    const messageId = ascendingId('msg');
+    const partId = ascendingId('prt');
+    const optimisticParts = text.trim()
+        ? [
+            {
+                id: partId,
+                sessionID: sessionId,
+                messageID: messageId,
+                type: 'text',
+                text,
+            },
+        ]
+        : [];
+    const info = {
+        id: messageId,
+        sessionID: sessionId,
+        role: 'user',
+        // No `time.created`: display order is by the BOX's `time.created`
+        // (`compareMessagesForDisplay`), and a stub stamped from the browser's
+        // clock sorted ABOVE real messages whenever the box ran behind it. An
+        // untimed stub is "the newest thing the user did", on every clock.
+        time: {},
+    };
+    useSyncStore.getState().optimisticAdd(sessionId, info, optimisticParts);
+    // No status write. `sessionStatus` is where the runtime's own SSE frames
+    // land, and a fabricated `busy` there outranked a real `GET .../turn` read
+    // stamped after it. `sendParts` files a `SendReceipt` instead — the claim
+    // this tab is actually entitled to make.
+    return { messageId, parts: [{ type: 'text', text, id: partId }] };
+}
 /** The error body, wherever the transport parked it. */
 function errorBody(error) {
     if (!error || typeof error !== 'object')
@@ -379,23 +480,12 @@ export function sendStateOnStart(text) {
 export function sendStateOnError(error) {
     return { pending: null, sendError: classifySendError(error) };
 }
-export function beginRestPromptObservation(sessionId, runtimeScope) {
-    beginSessionPromptObservation(sessionId, runtimeScope);
-    useSyncStore.getState().setStatus(sessionId, { type: 'busy' });
-}
-export function endRestPromptObservation(sessionId, runtimeScope) {
-    endSessionPromptObservation(sessionId, runtimeScope);
-    useSyncStore.getState().setStatus(sessionId, { type: 'idle' });
-}
-export async function sendRestPromptWithObservation(sessionId, runtimeScope, sendPrompt) {
-    beginRestPromptObservation(sessionId, runtimeScope);
-    try {
-        await sendPrompt();
-    }
-    catch (error) {
-        endRestPromptObservation(sessionId, runtimeScope);
-        throw error;
-    }
+/** The submission's tab-local name: the host's own key when it gave one, else
+ *  the optimistic part id this send is correlated by. Never sent anywhere —
+ *  it exists so a `working` state can say WHICH send it is standing on. */
+export function sendReceiptId(sessionId, parts, clientMessageId) {
+    const identified = parts.find((part) => 'id' in part && typeof part.id === 'string');
+    return clientMessageId ?? identified?.id ?? sessionId;
 }
 export async function rewindOpenCodeSession(sessionId, messageId) {
     if (!messageId)
@@ -478,6 +568,7 @@ export function useSession(projectId, sessionId, options = {}) {
         retryDelay: (failureCount, error) => isSessionStartError(error) && error.status === 404
             ? FRESH_START_404_RETRY_DELAY_MS
             : Math.min(1000 * 2 ** failureCount, 5000),
+        staleTime: sessionStartStaleTime,
         ...SESSION_START_POLL_OPTIONS,
     });
     const startData = start.data ?? null;
@@ -486,6 +577,41 @@ export function useSession(projectId, sessionId, options = {}) {
     const sandbox = startData?.sandbox ?? null;
     const startReady = stage === 'ready';
     const terminal = stage === 'failed' || stage === 'stopped';
+    // T8 defect 1 — `useRuntimeReconnect`'s first-mount
+    // `resetForServerSwitch()` (a plain `useEffect`) unconditionally seeds
+    // `status:'connecting', healthy:null` UNLESS `markRuntimeReadyVerified()`
+    // already told it the server proved this session ready. Task A's staleTime
+    // (above) means a remount can render `stage==='ready'` on its VERY FIRST
+    // render — before ANY effect, this hook's own switch/health-seed effects
+    // included, has had a chance to run — so whichever effect happens to fire
+    // first is not something to gamble on.
+    //
+    // `useLayoutEffect` is what makes this deterministic regardless of
+    // component-tree shape: React runs EVERY layout effect, tree-wide, before
+    // ANY passive effect (`useEffect`) fires — so this always wins the race
+    // against `useRuntimeReconnect`'s reset, whether that hook lives in a
+    // parent, a child, or a sibling of this one.
+    //
+    // Gated on `[projectId, sessionId]` (session identity), not `[startReady]`:
+    // it must only ever answer "was this session ALREADY proven ready at the
+    // moment I started mounting" — never "did it become ready later". A real
+    // network `/start` completing seconds after this mount's own reset has
+    // ALREADY run (and cleared whatever the flag held) would just leave a
+    // stale "ready" flag sitting in sessionStorage for the NEXT, unrelated
+    // session's first mount to wrongly consume. That later-ready case needs no
+    // help from this flag anyway: the health-seed effect (step 3, below)
+    // writes the connection store directly once `switched` flips, and
+    // `resetForServerSwitch()` never runs a second time to undo it — see
+    // `use-runtime-reconnect.test.ts`'s "mount-time ordering" tests for both
+    // orderings converging.
+    useIsomorphicLayoutEffect(() => {
+        if (!startEnabled)
+            return;
+        const cached = queryClient.getQueryState(sessionStartKey(projectId, sessionId));
+        if (cachedStartResultIsReady(cached))
+            markRuntimeReadyVerified();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [projectId, sessionId]);
     // Track how long /start has been returning nothing usable — no data, no
     // error — so `computeStartSettled` can bound the "given up" case (see
     // START_INCONCLUSIVE_GIVE_UP_MS) instead of waiting on a poll that a
@@ -592,6 +718,30 @@ export function useSession(projectId, sessionId, options = {}) {
         titleRefreshAbortRef.current?.abort();
         titleRefreshAbortRef.current = null;
     }, [projectId, sessionId]);
+    // ONE answer to "is this session working?", and it says where it came from.
+    //
+    // Four machines used to answer it and disagree: a prompt-observation phase
+    // machine with a stall timer, a busy override in the sync layer, a 30s
+    // safety timeout, and a 5s polling grace. `working` is a pure projection
+    // over the server's turn authority, the session's durable prompt inbox, the
+    // live stream, and — only until a server source that CAN know about it
+    // answers — this tab's own send receipt.
+    //
+    // Computed BEFORE `useSessionSync` because it is that hook's liveness switch:
+    // the transcript poll must follow the projection, not the stream slot a
+    // dropped frame can leave idle through a whole turn.
+    const working = useSessionWorking(projectId, sessionId, {
+        enabled,
+        runtimeSessionId: ocSessionId,
+    });
+    // The receipt lives in a per-session store, not in this component: the
+    // composer mounts its own `useSessionWorking` for the same session and they
+    // share one `/turn` cache entry. Two private receipts meant the observer
+    // without one wrote an uninformed read into that entry and defeated the
+    // other's. Nothing clears it on a server answer and nothing needs to — an
+    // observation the server could make AFTER accepting the send outranks it —
+    // so only the paths that know nothing is coming drop it.
+    const { noteSendReceipt, acceptSendReceipt, clearSendReceipt, noteAbortReceipt, settleAbortReceipt } = useSessionWorkingStore.getState();
     // Always call the hook (rules-of-hooks) so it stays in the same position
     // every render, but starve it with an empty session id when the chat engine
     // is off — `useSessionSync('')` fetches/polls nothing (its effects no-op on
@@ -600,22 +750,29 @@ export function useSession(projectId, sessionId, options = {}) {
     const rawSync = useSessionSync(chatEngine ? ocSessionId : '', {
         kortixSessionScope: `${projectId}/${sessionId}`,
         networkEnabled: switched,
+        working: working.state === 'working',
     });
     const sync = chatEngine ? rawSync : DISABLED_CHAT_ENGINE_SYNC;
     const runtimePhase = useRuntimePhase();
-    const [restRewind, setRestRewind] = useState(null);
+    // T22 — the revert record lives in the sync store, not component state.
+    // Component state made the boundary math wrong in two ways at once: it
+    // reset on every remount (stranding an invisible staged revert after a
+    // reload — the server still held the pointer, nothing here knew), and it
+    // was the ONLY thing to mirror server truth, so a `.staged`/`.cleared`/
+    // `.committed` wire event or another tab's action never reached this
+    // session's view at all. The store is the single place all of those
+    // sources (this hook's own `rewind()`/`restoreRewind()`, the three wire
+    // events via `handle-event.ts`, and a `Session.revert` field read on
+    // reload) converge — see `sync-store.ts`'s `sessionRevert` doc comment.
+    const restRewind = useSyncStore((s) => s.sessionRevert[ocSessionId] ?? null);
     const [rewindPending, setRewindPending] = useState(false);
     const [rewindError, setRewindError] = useState(null);
     const rewindMessageId = restRewind?.staged ? restRewind.messageId : null;
-    const messages = useMemo(() => messagesBeforeRewind(sync.messages, restRewind?.messageId ?? null), [sync.messages, restRewind?.messageId]);
+    const messages = useMemo(() => messagesBeforeRewind(sync.messages, restRewind), [sync.messages, restRewind]);
     useEffect(() => {
-        setRestRewind(null);
         setRewindPending(false);
         setRewindError(null);
     }, [sessionId, ocSessionId]);
-    useEffect(() => {
-        setRestRewind((current) => reconcileCommittedSessionRewind(sync.messages, current));
-    }, [sync.messages]);
     // 5b. Self-heal a missed `question.asked` SSE event (a `question` tool part
     // rendering as running with nothing in the pending store) — see
     // `useQuestionSelfHeal` for why this is distinct from the SSE reconnect-gap
@@ -632,7 +789,59 @@ export function useSession(projectId, sessionId, options = {}) {
     // keyed by request id carrying sessionID). useSessionSync does NOT surface them.
     const questionMap = useOpenCodePendingStore((s) => s.questions);
     const permissionMap = useOpenCodePendingStore((s) => s.permissions);
-    const isCompacting = useOpenCodeCompactionStore((state) => switched && Boolean(state.compactingBySession[ocSessionId]));
+    // Is this session COMPACTING? Two inputs, one projection — see
+    // `core/session/compaction.ts`. It used to be the raw client-only flag,
+    // cleared ONLY by the `session.compacted` SSE frame, so a missed frame pinned
+    // the composer for the lifetime of the tab and a compaction started anywhere
+    // else was invisible.
+    const optimisticCompactionAtMs = useOpenCodeCompactionStore((state) => switched ? (state.compactingBySession[ocSessionId] ?? null) : null);
+    // `Session.time.compacting` — the runtime's own record. This query is the
+    // same cache entry `session.compacted` and `session.updated` already write
+    // (`opencodeKeys.runtimeSession`), so reading it here costs no extra request
+    // in a host that mounts the session row anyway.
+    const runtimeSessionRow = useOpenCodeSession(switched ? ocSessionId : '');
+    const compactionInputs = {
+        optimisticAtMs: optimisticCompactionAtMs,
+        serverCompactingAtMs: runtimeSessionRow.data?.time?.compacting ?? null,
+        nowMs: Date.now(),
+    };
+    const isCompacting = projectCompacting(compactionInputs);
+    // The cap has to apply when NOTHING else re-renders — a lost
+    // `session.compacted` frame is exactly the case where no further event
+    // arrives — so the expiry instant is armed explicitly. Same mechanism, and
+    // the same reason, as `useSessionWorking`'s `workingExpiryAtMs` timer.
+    const [, setCompactionTick] = useState(0);
+    const compactionExpiry = compactionExpiryAtMs(compactionInputs);
+    useEffect(() => {
+        if (compactionExpiry === null)
+            return;
+        const timer = setTimeout(() => setCompactionTick((tick) => tick + 1), Math.max(0, compactionExpiry - Date.now()) + 1);
+        return () => clearTimeout(timer);
+    }, [compactionExpiry]);
+    // The server-observed branch of `projectCompacting` (rule 1) is otherwise
+    // unbounded: it stays authoritative until `opencodeKeys.runtimeSession`'s
+    // cached row is refreshed, and the only event wired to refresh it
+    // (`session.compacted`, in `use-opencode-events/handle-event.ts`) is one
+    // SSE frame that can be lost — a backgrounded tab, a stream reconnect, or
+    // that handler's own refetch failing. Without this, a lost frame pins
+    // `isCompacting` — and therefore the composer and slash-commands
+    // (`session-chat.tsx`'s `effectiveBusy`) — for the rest of the tab's life.
+    // This forces a REAL, retry-backed re-check (through the same query
+    // `useOpenCodeSession` above already runs, so it inherits its 3-attempt
+    // exponential-backoff retry) once the observed flag has gone unconfirmed
+    // for `SERVER_COMPACTION_REVALIDATE_MS` — independent of whether
+    // `session.compacted` ever arrives. If the server still reports
+    // compacting, the fresh timestamp re-arms this same timer; once it does
+    // not, `serverCompactingAtMs` clears and the projection follows.
+    const serverCompactionRevalidateAt = serverCompactionRevalidateAtMs(compactionInputs);
+    useEffect(() => {
+        if (serverCompactionRevalidateAt === null || !switched || !ocSessionId)
+            return;
+        const timer = setTimeout(() => {
+            void queryClient.invalidateQueries({ queryKey: opencodeKeys.runtimeSession(ocSessionId) });
+        }, Math.max(0, serverCompactionRevalidateAt - Date.now()));
+        return () => clearTimeout(timer);
+    }, [serverCompactionRevalidateAt, switched, ocSessionId, queryClient]);
     const removeQuestion = useOpenCodePendingStore((s) => s.removeQuestion);
     const removePermission = useOpenCodePendingStore((s) => s.removePermission);
     const questions = useMemo(() => (switched ? Object.values(questionMap).filter((q) => q.sessionID === ocSessionId) : []), [questionMap, ocSessionId, switched]);
@@ -669,17 +878,17 @@ export function useSession(projectId, sessionId, options = {}) {
     const [sendState, setSendState] = useState(IDLE_SEND_STATE);
     const pending = sendState.pending;
     const pendingBaseCount = useRef(0);
+    // Cleared when the send's echo lands — a real observation. The 30s timeout
+    // that used to sit beside this is deleted: no in-repo consumer reads
+    // `pending`, and where it could fire it fired wrongly — 30s is shorter than
+    // a legitimate inbox path (18.9s Daytona / 24.5s Platinum boot plus the
+    // drain). The sync store's optimistic message and the `SendReceipt` carry
+    // the state it approximated, each with an honest bound.
     useEffect(() => {
         if (pending && userMsgCount > pendingBaseCount.current) {
             setSendState((s) => (s.pending ? { ...s, pending: null } : s));
         }
     }, [userMsgCount, pending]);
-    useEffect(() => {
-        if (!pending)
-            return;
-        const t = setTimeout(() => setSendState((s) => (s.pending ? { ...s, pending: null } : s)), 30_000);
-        return () => clearTimeout(t);
-    }, [pending]);
     const sendParts = async (parts, override) => {
         if (!runtimeActionReady)
             throw new RuntimeNotReadyError();
@@ -700,19 +909,48 @@ export function useSession(projectId, sessionId, options = {}) {
         // which is what keeps it on screen for the whole of a slow upload instead
         // of being deleted by a rehydrate that only carries older turns.
         markDispatchedForPartIds(ocSessionId, parts);
-        await sendRestPromptWithObservation(ocSessionId, sandbox?.external_id ?? undefined, () => sendMutation.mutateAsync({
-            sessionId: ocSessionId,
-            parts,
-            ...(Object.keys(opts).length ? { options: opts } : {}),
-        }));
-        setRestRewind(commitSessionRewind);
+        const receipt = {
+            messageId: sendReceiptId(ocSessionId, parts, override?.clientMessageId),
+            atMs: Date.now(),
+        };
+        noteSendReceipt(sessionId, receipt);
+        try {
+            await sendMutation.mutateAsync({
+                sessionId: ocSessionId,
+                parts,
+                ...(Object.keys(opts).length ? { options: opts } : {}),
+                ...(override?.clientMessageId ? { clientMessageId: override.clientMessageId } : {}),
+            });
+            // The server has the prompt. From here — and NOT before — a `/turn` read
+            // is able to see it, so one is allowed to answer for it.
+            acceptSendReceipt(sessionId, receipt.messageId, Date.now());
+        }
+        catch (error) {
+            // The prompt never reached the server, so there is nothing to wait for.
+            // Dropping the receipt here is what stops a refused send from claiming
+            // `working` for a minute over a turn that will never start. NAMED, so a
+            // slow failure cannot drop a later send's receipt while its own request
+            // is still on the wire.
+            clearSendReceipt(sessionId, receipt.messageId);
+            throw error;
+        }
+        useSyncStore.getState().commitSessionRevert(ocSessionId);
     };
     const send = (text, override) => {
         if (!runtimeActionReady)
             return;
         pendingBaseCount.current = userMsgCount;
         setSendState(sendStateOnStart(text));
-        void sendParts([{ type: 'text', text }], override).catch((error) => {
+        // T15 — one user bubble: the optimistic message and the outgoing
+        // part share one minted id, so the server's echo can be correlated back
+        // to it instead of leaving both on screen until the idle sweep.
+        const { messageId, parts } = beginOptimisticPlainTextSend(ocSessionId, text);
+        void sendParts(parts, override).catch((error) => {
+            // The send never reached (or was refused by) the server — nothing to
+            // rehydrate, so drop the optimistic message outright rather than leave
+            // it stranded forever (mirrors `abandonOptimisticSend`).
+            // `sendParts` already dropped this tab's send receipt on this path.
+            useSyncStore.getState().optimisticRemove(ocSessionId, messageId);
             setSendState(sendStateOnError(error));
         });
     };
@@ -727,14 +965,14 @@ export function useSession(projectId, sessionId, options = {}) {
             throw new RuntimeNotReadyError();
         if (!messageId)
             throw new Error('Session rewind requires a message id');
-        if (sync.isBusy || pending || rewindPending) {
+        if (working.state === 'working' || rewindPending) {
             throw new Error('Cannot rewind a busy session');
         }
         setRewindPending(true);
         setRewindError(null);
         try {
             await rewindOpenCodeSession(ocSessionId, messageId);
-            setRestRewind({ messageId, staged: true });
+            useSyncStore.getState().stageSessionRevert(ocSessionId, messageId);
         }
         catch (error) {
             const classified = classifySendError(error);
@@ -754,7 +992,7 @@ export function useSession(projectId, sessionId, options = {}) {
         setRewindError(null);
         try {
             await restoreOpenCodeSessionRewind(ocSessionId);
-            setRestRewind(null);
+            useSyncStore.getState().clearSessionRevert(ocSessionId);
         }
         catch (error) {
             const classified = classifySendError(error);
@@ -765,15 +1003,45 @@ export function useSession(projectId, sessionId, options = {}) {
             setRewindPending(false);
         }
     };
-    // The one true cancel: abort the run AND drop any pending prompt + open prompts.
+    // The one true cancel: abort the run AND drop any pending prompt + open
+    // prompts. Returns a promise that settles once the abort is acknowledged —
+    // the mutation resolved (and, per `abortOpenCodeSession`, the session's
+    // status was re-read to confirm idle), the mutation failed after its own
+    // retries, or a bounded ~5s timeout elapsed. See `AbortSettlement`.
+    //
+    // T9: `abortInFlightDeliveries` runs FIRST, synchronously — a prompt
+    // still retrying its boot/wake backoff when the user hits Stop must never
+    // land after this point and run against the old text. The optimistic UI
+    // (busy → idle, questions/permissions cleared) still updates instantly;
+    // only the returned promise is new — a caller that never awaits it sees
+    // exactly the same synchronous effects as before.
     const cancel = () => {
         if (runtimeActionReady) {
-            endRestPromptObservation(ocSessionId);
-            abortMutation.mutate(ocSessionId);
+            clearSendReceipt(sessionId);
+            // The stop's own receipt. The cancel needs a round trip through the
+            // control plane and the daemon before turn authority is released, so
+            // every `/turn` read issued before it settles still reports the doomed
+            // turn — including the one the optimistic idle frame below triggers.
+            // Without this the composer flipped Send back to Stop ~120ms after the
+            // click and stayed there for the whole abort. See `AbortReceipt`.
+            noteAbortReceipt(sessionId, Date.now());
+            // No fabricated idle frame here: the receipt above IS the optimistic
+            // idle, with provenance and a bound. A fabricated frame outranked the
+            // control plane's `/turn` answer in `projectWorking` for the whole
+            // abort round-trip — the laundering this migration removes.
+            abortInFlightDeliveries(ocSessionId);
         }
         questions.forEach((q) => removeQuestion(q.id));
         permissions.forEach((p) => removePermission(p.id));
         setSendState(IDLE_SEND_STATE);
+        if (!runtimeActionReady)
+            return Promise.resolve({ status: 'skipped' });
+        const settlement = awaitAbortSettlement(() => abortMutation.mutateAsync(ocSessionId));
+        // `awaitAbortSettlement` never rejects — it resolves with how the abort
+        // ended (acknowledged, failed, or timed out). Any of those is the instant
+        // from which a server read can see the abort's effect, or fail to.
+        void settlement.then(() => settleAbortReceipt(sessionId, Date.now()));
+        return settlement;
     };
     const runtimeSessionError = canonicalSession.error;
     const phase = derivePhase({
@@ -809,6 +1077,13 @@ export function useSession(projectId, sessionId, options = {}) {
             picks.setModel(stash.model);
         if (stash.agent)
             picks.setAgent(stash.agent);
+        // A picks-only stash (`prompt: ''`) seeds the selections above and sends
+        // NOTHING: apps/web's producers now deliver the first prompt as a durable
+        // inbox row (server-side at create, or `startSessionWithPrompt`), and the
+        // stash carries only the model/agent hand-off. A full stash — the
+        // whitelabel-demo producer — still replays here exactly as before.
+        if (!stash.prompt.trim())
+            return;
         send(stash.prompt, {
             model: stash.model,
             agent: stash.agent,
@@ -840,6 +1115,17 @@ export function useSession(projectId, sessionId, options = {}) {
         phase,
         /** Raw /start stage (provisioning|starting|ready|stopped|failed), for boot UI. */
         stage,
+        /**
+         * The immutable agent this project session was created with, from /start
+         * (`agent_name`). Known from the FIRST /start response — long before the
+         * sandbox is ready — so composers can render the session's real agent
+         * while it boots instead of guessing from the roster. The server
+         * serializes `'default'` when no agent was bound; that is not a real
+         * roster agent, so it surfaces as `null` here.
+         */
+        agentName: startData?.agent_name && startData.agent_name !== 'default'
+            ? startData.agent_name
+            : null,
         /** The serialized session_sandboxes row from /start (status, metadata, ids), or null. */
         sandbox,
         /** True once the runtime is switched in and ready (equivalent to phase==='ready'). */
@@ -852,7 +1138,10 @@ export function useSession(projectId, sessionId, options = {}) {
         failure: startData?.failure ?? null,
         /** Granular boot phase (connecting|booting|ready|unreachable) for detailed UI. */
         runtimePhase,
-        isBusy: sync.isBusy || !!pending,
+        /** Provenance-tagged working state — WHICH observation decided it, when,
+         *  and for which turn. The one answer; `isBusy` is its boolean face. */
+        working,
+        isBusy: working.state === 'working',
         isCompacting,
         isLoading: sync.isLoading,
         isError: terminal || !!startError || !!runtimeSessionError,