@kortix/ui 0.0.0-stage → 0.14.4

package/dist/session/status/session-surface.d.ts

@@ -0,0 +1,175 @@
+/**
+ * What the session route paints, as one pure decision.
+ *
+ * The route used to decide this inline, from a pair of refs mutated DURING
+ * RENDER (`lifecycleForRef` / `freshRef`) next to `setState` calls made in that
+ * same render pass. Those two halves are not equally durable. Every client-side
+ * navigation runs inside a transition, and React is free to throw a transition
+ * render away and start over — a ref write survives that, a queued state update
+ * does not. So the halves could disagree: `freshRef` saying "brand-new session"
+ * while `shellSubmitted` was still false. And that pair DEADLOCKED —
+ *
+ *   the new-session shell suppressed mounting the chat
+ *     → the chat was the only thing that could report readiness
+ *       → readiness was the only thing that dismissed the shell
+ *
+ * — so an existing session with a full transcript painted the empty "give this
+ * project something to work on" surface, and stayed there until a hard reload.
+ * That is the bug this module exists to make unrepresentable. Two rules:
+ *
+ *  1. The new-session surface is DERIVED, never latched. Any evidence that this
+ *     session already has a transcript revokes it, immediately.
+ *  2. Nothing about that surface can permanently withhold the chat. The only
+ *     thing gating the chat is whether there is a transcript pin to mount it on.
+ *
+ * The route feeds these from state it seeds once per session (it is keyed by
+ * session id, so a switch remounts it) plus live data, and never from a ref it
+ * edits mid-render.
+ */
+import type { UseSessionResult } from '@kortix/sdk/react';
+export interface SessionSurfaceInput {
+    /**
+     * This tab created this session, or arrived carrying its first prompt — i.e.
+     * the local, optimistic "this is brand new" hint. Deliberately a hint: it
+     * comes from in-memory/session-storage state that outlives the thing it
+     * describes, so it is never trusted on its own.
+     */
+    newSessionHint: boolean;
+    /** The durable first prompt exists, even after this tab loses its local hint. */
+    hasPendingFirstPrompt?: boolean;
+    /**
+     * The saved copy proves this existing session's conversation empty, no turn
+     * ended since, and nothing is queued (`useSession().conversationEmpty`). It
+     * opens like a new one, on its composer: a boot screen would wait for
+     * history that does not exist.
+     */
+    conversationEmpty?: boolean;
+    /** Any transcript content is known for this session (live runtime OR cache). */
+    hasTranscript: boolean;
+}
+/**
+ * Is this the brand-new-session surface (the instant shell) rather than a
+ * session being resumed?
+ *
+ * `hasTranscript` is the veto, and it is the whole point: a stale hint can now
+ * only ever cost a beat of the wrong overlay, never a dead end. The transcript
+ * reaches the route from `useSession`'s own sync — which paints from the local
+ * IndexedDB cache without waiting on a sandbox — so the veto lands even while
+ * the box is still booting, and does not depend on the chat having mounted.
+ */
+export declare function isNewSessionSurface(input: SessionSurfaceInput): boolean;
+export interface MountSessionChatInput extends SessionSurfaceInput {
+    /** A transcript pin is known, so the chat has something to mount on. */
+    contentAvailable: boolean;
+    /** The user committed a first message on the instant shell. */
+    submitted: boolean;
+}
+/**
+ * May the real chat mount?
+ *
+ * A brand-new session holds it back until the user actually sends something —
+ * the instant shell is the typing surface until then, and mounting a second
+ * composer underneath it would fight for focus. That hold is safe ONLY because
+ * {@link isNewSessionSurface} is revoked by transcript evidence: a session with
+ * history is never "brand new", so it can never be held back.
+ */
+export declare function shouldMountSessionChat(input: MountSessionChatInput): boolean;
+/** The pre-chat overlay: the typeable new-session shell, or the boot loader. */
+export type SessionOverlay = 'new-session-shell' | 'boot-loader';
+/**
+ * Which overlay covers the chat while it cannot paint yet. The caller decides
+ * WHETHER an overlay is up (it fades out on `chatReady`); this decides WHICH.
+ *
+ * `shellShowsFirstPrompt` pins the shell down while it is painting the user's
+ * own first message. Their prompt reaches the transcript store — flipping
+ * `hasTranscript` — well before the chat has crossfaded in, and without this
+ * pin the overlay swaps the bubble and its "Thinking" row for a boot spinner
+ * for the whole of that window. That is not a beat: `shouldMountSessionChat`
+ * unblocks on the same flag flip, so the spinner is up for as long as
+ * `SessionChat` takes to mount and reach its first paint. It reads as the shell
+ * vanishing and the session starting over.
+ *
+ * It is deliberately NOT `submitted`/`submittedOnShell`. This flag once meant
+ * "typed into the shell", which is only ONE of the two ways a first prompt gets
+ * here — and not the common one. Sending from the project home creates the
+ * session, POSTs the prompt as a durable inbox row, navigates, and leaves the
+ * text in `useFirstPromptPreviewStore` for the shell to draw. Same bubble on
+ * screen, same need to be pinned, but the send happened on the previous page,
+ * so the old flag was false for exactly the flow most sessions start with.
+ *
+ * The caller must not widen this to any evidence a prompt EXISTS. The
+ * start-stash can outlive the hand-off it describes; the pin is for a first
+ * prompt this shell is painting right now.
+ */
+export declare function resolveSessionOverlay(input: SessionSurfaceInput & {
+    shellShowsFirstPrompt: boolean;
+}): SessionOverlay;
+/**
+ * How the boot state is PRESENTED once the overlay's identity is settled.
+ *
+ * The two are different questions and collapsing them is what produced the
+ * complaint this exists for: opening a hibernated session showed a full-screen
+ * "Connecting…" for the whole wake (5-240 s) with the transcript hidden behind
+ * it — even though, with a server-side transcript mirror, the conversation is
+ * available on the first frame.
+ *
+ * The rule: an overlay may cover the chat only while there is nothing under it
+ * worth reading. The moment a transcript exists, boot status becomes a compact
+ * banner ABOVE the conversation instead of a wall in front of it. Sending is
+ * unaffected either way — the composer carries its own "waking, your message
+ * will be queued" notice, and a prompt submitted during a wake becomes a
+ * durable inbox row.
+ *
+ * `new-session-shell` is never demoted: it is a typing surface, not a status
+ * screen, and there is by definition no transcript under it.
+ */
+export type SessionBootPresentation = 'full-screen' | 'banner';
+export declare function resolveBootPresentation(input: {
+    overlay: SessionOverlay;
+    hasTranscript: boolean;
+}): SessionBootPresentation;
+/** `useSession().savedTranscript`: can the saved conversation show yet? */
+export type SavedTranscript = UseSessionResult['savedTranscript'];
+/** What the boot overlay paints for a session that is being resumed. */
+export type ResumeOverlay = 'saved-skeleton' | 'boot-loader';
+/**
+ * Skeleton rows or the boot screen, for a session that is not brand new.
+ *
+ * The control plane keeps a saved copy of the conversation and answers in one
+ * round trip; the computer takes 5-240 s to wake. So while that copy is on its
+ * way the overlay shows the session with skeleton message rows, and the
+ * conversation replaces them in one step. Only a session with nothing saved
+ * (`none`) keeps the boot screen, because nothing can be read until the
+ * runtime is up. `shown` stays on the skeleton: the overlay is fading out over
+ * the conversation at that point, and switching it to the boot screen for the
+ * fade would flash the wrong surface.
+ */
+export declare function resolveResumeOverlay(input: {
+    savedTranscript: SavedTranscript;
+}): ResumeOverlay;
+/**
+ * Is there a conversation to read on this route, or one on its way?
+ *
+ * The stopped-sandbox and waking branches step aside for a transcript already
+ * on screen and fall through to the chat mount. A saved copy that is still
+ * loading gets the same treatment, so for its one round trip the overlay shows
+ * skeleton rows instead of a restart card or the boot screen.
+ */
+export declare function hasOrExpectsTranscript(input: {
+    hasTranscript: boolean;
+    savedTranscript: SavedTranscript;
+}): boolean;
+/**
+ * Should the local "brand new session" hint be forgotten?
+ *
+ * The hint used to be dropped only once the chat reported ready — which never
+ * happened on exactly the sessions where the hint was wrong, so a wrong hint was
+ * self-preserving. Any of these means the hint has done its job (or was wrong):
+ * the chat painted, the session turned out to have history, or the user sent
+ * their first message.
+ */
+export declare function shouldForgetNewSessionHint(input: {
+    chatReady: boolean;
+    hasTranscript: boolean;
+    submitted: boolean;
+}): boolean;

package/dist/session/status/session-surface.js

@@ -0,0 +1,129 @@
+/**
+ * What the session route paints, as one pure decision.
+ *
+ * The route used to decide this inline, from a pair of refs mutated DURING
+ * RENDER (`lifecycleForRef` / `freshRef`) next to `setState` calls made in that
+ * same render pass. Those two halves are not equally durable. Every client-side
+ * navigation runs inside a transition, and React is free to throw a transition
+ * render away and start over — a ref write survives that, a queued state update
+ * does not. So the halves could disagree: `freshRef` saying "brand-new session"
+ * while `shellSubmitted` was still false. And that pair DEADLOCKED —
+ *
+ *   the new-session shell suppressed mounting the chat
+ *     → the chat was the only thing that could report readiness
+ *       → readiness was the only thing that dismissed the shell
+ *
+ * — so an existing session with a full transcript painted the empty "give this
+ * project something to work on" surface, and stayed there until a hard reload.
+ * That is the bug this module exists to make unrepresentable. Two rules:
+ *
+ *  1. The new-session surface is DERIVED, never latched. Any evidence that this
+ *     session already has a transcript revokes it, immediately.
+ *  2. Nothing about that surface can permanently withhold the chat. The only
+ *     thing gating the chat is whether there is a transcript pin to mount it on.
+ *
+ * The route feeds these from state it seeds once per session (it is keyed by
+ * session id, so a switch remounts it) plus live data, and never from a ref it
+ * edits mid-render.
+ */
+/**
+ * Is this the brand-new-session surface (the instant shell) rather than a
+ * session being resumed?
+ *
+ * `hasTranscript` is the veto, and it is the whole point: a stale hint can now
+ * only ever cost a beat of the wrong overlay, never a dead end. The transcript
+ * reaches the route from `useSession`'s own sync — which paints from the local
+ * IndexedDB cache without waiting on a sandbox — so the veto lands even while
+ * the box is still booting, and does not depend on the chat having mounted.
+ */
+export function isNewSessionSurface(input) {
+    return ((input.newSessionHint || !!input.hasPendingFirstPrompt || !!input.conversationEmpty) &&
+        !input.hasTranscript);
+}
+/**
+ * May the real chat mount?
+ *
+ * A brand-new session holds it back until the user actually sends something —
+ * the instant shell is the typing surface until then, and mounting a second
+ * composer underneath it would fight for focus. That hold is safe ONLY because
+ * {@link isNewSessionSurface} is revoked by transcript evidence: a session with
+ * history is never "brand new", so it can never be held back.
+ */
+export function shouldMountSessionChat(input) {
+    if (!input.contentAvailable)
+        return false;
+    return !isNewSessionSurface(input) || input.submitted || !!input.hasPendingFirstPrompt;
+}
+/**
+ * Which overlay covers the chat while it cannot paint yet. The caller decides
+ * WHETHER an overlay is up (it fades out on `chatReady`); this decides WHICH.
+ *
+ * `shellShowsFirstPrompt` pins the shell down while it is painting the user's
+ * own first message. Their prompt reaches the transcript store — flipping
+ * `hasTranscript` — well before the chat has crossfaded in, and without this
+ * pin the overlay swaps the bubble and its "Thinking" row for a boot spinner
+ * for the whole of that window. That is not a beat: `shouldMountSessionChat`
+ * unblocks on the same flag flip, so the spinner is up for as long as
+ * `SessionChat` takes to mount and reach its first paint. It reads as the shell
+ * vanishing and the session starting over.
+ *
+ * It is deliberately NOT `submitted`/`submittedOnShell`. This flag once meant
+ * "typed into the shell", which is only ONE of the two ways a first prompt gets
+ * here — and not the common one. Sending from the project home creates the
+ * session, POSTs the prompt as a durable inbox row, navigates, and leaves the
+ * text in `useFirstPromptPreviewStore` for the shell to draw. Same bubble on
+ * screen, same need to be pinned, but the send happened on the previous page,
+ * so the old flag was false for exactly the flow most sessions start with.
+ *
+ * The caller must not widen this to any evidence a prompt EXISTS. The
+ * start-stash can outlive the hand-off it describes; the pin is for a first
+ * prompt this shell is painting right now.
+ */
+export function resolveSessionOverlay(input) {
+    if (input.shellShowsFirstPrompt)
+        return 'new-session-shell';
+    return isNewSessionSurface(input) ? 'new-session-shell' : 'boot-loader';
+}
+export function resolveBootPresentation(input) {
+    if (input.overlay !== 'boot-loader')
+        return 'full-screen';
+    return input.hasTranscript ? 'banner' : 'full-screen';
+}
+/**
+ * Skeleton rows or the boot screen, for a session that is not brand new.
+ *
+ * The control plane keeps a saved copy of the conversation and answers in one
+ * round trip; the computer takes 5-240 s to wake. So while that copy is on its
+ * way the overlay shows the session with skeleton message rows, and the
+ * conversation replaces them in one step. Only a session with nothing saved
+ * (`none`) keeps the boot screen, because nothing can be read until the
+ * runtime is up. `shown` stays on the skeleton: the overlay is fading out over
+ * the conversation at that point, and switching it to the boot screen for the
+ * fade would flash the wrong surface.
+ */
+export function resolveResumeOverlay(input) {
+    return input.savedTranscript === 'none' ? 'boot-loader' : 'saved-skeleton';
+}
+/**
+ * Is there a conversation to read on this route, or one on its way?
+ *
+ * The stopped-sandbox and waking branches step aside for a transcript already
+ * on screen and fall through to the chat mount. A saved copy that is still
+ * loading gets the same treatment, so for its one round trip the overlay shows
+ * skeleton rows instead of a restart card or the boot screen.
+ */
+export function hasOrExpectsTranscript(input) {
+    return input.hasTranscript || input.savedTranscript === 'loading';
+}
+/**
+ * Should the local "brand new session" hint be forgotten?
+ *
+ * The hint used to be dropped only once the chat reported ready — which never
+ * happened on exactly the sessions where the hint was wrong, so a wrong hint was
+ * self-preserving. Any of these means the hint has done its job (or was wrong):
+ * the chat painted, the session turned out to have history, or the user sent
+ * their first message.
+ */
+export function shouldForgetNewSessionHint(input) {
+    return input.chatReady || input.hasTranscript || input.submitted;
+}

package/dist/session/status/session-tab-title-sync.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Keeps the tab title correct AFTER the route's metadata has settled — a
+ * rename, or the agent's auto-title landing seconds into a new session.
+ *
+ * This is deliberately NOT a second owner of the title. `generateMetadata` in
+ * the session layout resolves the same string from the same fields, so on load
+ * the two agree and the guarded write below is a no-op. The only writes that
+ * ever reach the DOM from here are genuine post-load changes to the name.
+ *
+ * It cannot be the primary owner: React re-asserts the metadata-owned <title>
+ * when it commits, which happens after client effects run, so a client write
+ * during load is overwritten (measured: written at 306ms, gone at 324ms).
+ *
+ * Rendered by the layout, never by the page, so the session page tree gains no
+ * subscriber and no re-render.
+ */
+export declare function SessionTabTitleSync({ projectId, sessionId, }: {
+    projectId: string;
+    sessionId: string;
+}): null;

package/dist/session/status/session-tab-title-sync.js

@@ -0,0 +1,44 @@
+'use client';
+import { useEffect } from 'react';
+import { useProjectSession } from '@kortix/sdk/react';
+import { sessionTabTitleFromSession } from './session-tab-title.js';
+/**
+ * Keeps the tab title correct AFTER the route's metadata has settled — a
+ * rename, or the agent's auto-title landing seconds into a new session.
+ *
+ * This is deliberately NOT a second owner of the title. `generateMetadata` in
+ * the session layout resolves the same string from the same fields, so on load
+ * the two agree and the guarded write below is a no-op. The only writes that
+ * ever reach the DOM from here are genuine post-load changes to the name.
+ *
+ * It cannot be the primary owner: React re-asserts the metadata-owned <title>
+ * when it commits, which happens after client effects run, so a client write
+ * during load is overwritten (measured: written at 306ms, gone at 324ms).
+ *
+ * Rendered by the layout, never by the page, so the session page tree gains no
+ * subscriber and no re-render.
+ */
+export function SessionTabTitleSync({ projectId, sessionId, }) {
+    // Reads the session's OWN cache entry, not the project's session list.
+    //
+    // It used to subscribe to the flat list with `enabled: false` and find its
+    // row in it. That stopped working when the sidebar's list became a bounded
+    // page under a different cache key: this observer would have sat on an entry
+    // nobody writes any more, and the tab title would never update. The single
+    // row is also the correct dependency — the tab shows one session's name.
+    //
+    // `useProjectSession` is a real query, so a rename (which writes through
+    // every cached session shape, see `updateCachedProjectSessions`) reaches the
+    // tab immediately, and a session opened from a cold cache still resolves.
+    const { data: session } = useProjectSession(projectId, sessionId);
+    const title = session ? sessionTabTitleFromSession(session) : null;
+    useEffect(() => {
+        if (!title)
+            return;
+        // Write only on a real change. Assigning an identical string still mutates
+        // the <title> node, and this must stay quiet enough to be invisible.
+        if (document.title !== title)
+            document.title = title;
+    }, [title]);
+    return null;
+}

package/dist/session/status/session-tab-title.d.ts

@@ -0,0 +1,33 @@
+import type { ProjectSession } from '@kortix/sdk';
+/**
+ * The browser tab title for one session, as ONE pure function.
+ *
+ * Why a pure function rather than a hook: the title is produced in two
+ * runtimes — Node, inside the route's `generateMetadata`, and the browser, when
+ * the session is renamed after load. Both call this, so both emit a
+ * byte-identical string and the hand-off from server metadata to the client
+ * updater is invisible instead of a flash.
+ *
+ * Deliberately NOT `sessionDisplayLabel` (components/projects/session-label.ts):
+ * that helper's fallback chain ends at `session.session_id.slice(0, 8)`, which
+ * would paint a raw uuid fragment into the tab strip. A tab is read at a glance
+ * out of the corner of an eye; "3f9a1c2b" is noise there, "New session" is
+ * information.
+ */
+/** Longest session name kept before it is elided, INCLUDING the ellipsis. */
+export declare const SESSION_TAB_TITLE_MAX_NAME = 60;
+/**
+ * `<session name> — Kortix`. An absent name means the session could not be
+ * read, so it gets the explicit unavailable label: never an empty title, never
+ * a raw id.
+ */
+export declare function sessionTabTitle(name: string | null | undefined): string;
+/**
+ * `sessionTabTitle` for a session record, or the unavailable title if absent.
+ *
+ * The name comes from `getSessionDisplayTitle` — the SAME function the sidebar,
+ * the session list, and the tab bar render — so a session reads identically in
+ * the tab and in the app, including its "New session" placeholder. Deriving the
+ * precedence a second time here is how the two would drift apart.
+ */
+export declare function sessionTabTitleFromSession(session: ProjectSession | null | undefined): string;

package/dist/session/status/session-tab-title.js

@@ -0,0 +1,60 @@
+import { getSessionDisplayTitle } from '../actions/project-session-list-helpers.js';
+import { siteMetadata } from '../../internal/lib/site-metadata.js';
+/**
+ * The browser tab title for one session, as ONE pure function.
+ *
+ * Why a pure function rather than a hook: the title is produced in two
+ * runtimes — Node, inside the route's `generateMetadata`, and the browser, when
+ * the session is renamed after load. Both call this, so both emit a
+ * byte-identical string and the hand-off from server metadata to the client
+ * updater is invisible instead of a flash.
+ *
+ * Deliberately NOT `sessionDisplayLabel` (components/projects/session-label.ts):
+ * that helper's fallback chain ends at `session.session_id.slice(0, 8)`, which
+ * would paint a raw uuid fragment into the tab strip. A tab is read at a glance
+ * out of the corner of an eye; "3f9a1c2b" is noise there, "New session" is
+ * information.
+ */
+/** Longest session name kept before it is elided, INCLUDING the ellipsis. */
+export const SESSION_TAB_TITLE_MAX_NAME = 60;
+/** Separator between the session name and the app name. */
+const SEPARATOR = ' — ';
+/**
+ * Shown when the session could not be read at all (404, no auth, timeout).
+ *
+ * Distinct from an untitled session, which `getSessionDisplayTitle` already
+ * names "New session" — "we could not read this" and "this has no name yet"
+ * are different facts and must not share a label.
+ */
+const UNAVAILABLE = 'Session';
+/** One line, no runs of whitespace — a tab cannot render a newline anyway. */
+function flatten(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+function elide(value) {
+    if (value.length <= SESSION_TAB_TITLE_MAX_NAME)
+        return value;
+    return `${value.slice(0, SESSION_TAB_TITLE_MAX_NAME - 1).trimEnd()}…`;
+}
+/**
+ * `<session name> — Kortix`. An absent name means the session could not be
+ * read, so it gets the explicit unavailable label: never an empty title, never
+ * a raw id.
+ */
+export function sessionTabTitle(name) {
+    const clean = name ? flatten(name) : '';
+    return `${elide(clean || UNAVAILABLE)}${SEPARATOR}${siteMetadata.name}`;
+}
+/**
+ * `sessionTabTitle` for a session record, or the unavailable title if absent.
+ *
+ * The name comes from `getSessionDisplayTitle` — the SAME function the sidebar,
+ * the session list, and the tab bar render — so a session reads identically in
+ * the tab and in the app, including its "New session" placeholder. Deriving the
+ * precedence a second time here is how the two would drift apart.
+ */
+export function sessionTabTitleFromSession(session) {
+    if (!session)
+        return sessionTabTitle(null);
+    return sessionTabTitle(getSessionDisplayTitle(session));
+}

package/dist/session/status/session-terminal-state.d.ts

@@ -0,0 +1,70 @@
+/** Raw `/start` stage, or `null` while the first `/start` is still in flight. */
+export type SessionStartStageValue = 'provisioning' | 'starting' | 'ready' | 'stopped' | 'failed' | null;
+export interface SessionTerminalState {
+    /** Raw `/start` stage — the ONLY server-declared terminal signal. */
+    stage: SessionStartStageValue;
+    /** `/start` `retriable`: true while polling can still make progress. */
+    retriable: boolean;
+    hasStartError: boolean;
+    sandboxStatus?: string | null;
+}
+/**
+ * Detect a terminal `/start` FAILURE that has no serialized sandbox row.
+ *
+ * Read `stage`, never `phase`. `useSession` collapses three unrelated
+ * conditions into `phase === 'error'`: a terminal stage, a typed `/start`
+ * error, AND a transient OpenCode REST error. Deriving "provisioning failed
+ * before allocation" from `phase` therefore fired on states that are not a
+ * provisioning failure at all — a session the server reports as `stopped`, and
+ * a session still booting (`stage: 'starting'`, `sandbox: null`, `retriable:
+ * true`) whose runtime list happened to error. Both painted a terminal
+ * "Couldn't start session" card over a session that had not failed.
+ *
+ * `retriable` is the server's own "polling can still make progress" flag, so an
+ * unfinished boot can never be reported as a dead end even if a future stage
+ * value lands here.
+ */
+export declare function isUnmaterializedSessionFailure(state: SessionTerminalState): boolean;
+/**
+ * Detect a session the server reports as `stopped` with no serialized sandbox
+ * row (`openSession`'s terminal branch for a `stopped`/`completed` session row).
+ *
+ * It needs its own branch because the page's `fatal` path reads
+ * `sandbox.status`, which is unavailable here — so this state used to fall
+ * through to the unmaterialized-FAILURE card and tell the user a session that
+ * merely stopped had "failed before its computer was created".
+ */
+export declare function isDormantSessionWithoutRuntime(state: SessionTerminalState): boolean;
+/** The subset of `fatal`'s inputs this decision needs. */
+export interface StoppedSandboxCacheState {
+    /** `sandbox.status` from the route's `fatal` gate — only `'stopped'`/`'error'` matter here. */
+    sandboxStatus: string | null | undefined;
+    /**
+     * Renderable content already exists for this session without a live
+     * runtime — cached transcript messages (SDK sync store, painted from
+     * IndexedDB/memory; see `use-session-sync.ts`) or an optimistic prompt in
+     * flight. The cheapest truthful signal, read from the route's own
+     * `hasTranscript`/pending-prompt state — never recomputed here.
+     */
+    hasCachedContent: boolean;
+}
+/**
+ * A `stopped`/`error` sandbox whose session already has renderable cached
+ * content should render the TRANSCRIPT with a calm waking affordance, not the
+ * full-screen restart/waking card `fatal` used to force unconditionally.
+ *
+ * Reading what you already wrote never needs a sandbox — Gate B in
+ * `session-chat.tsx` (`resolveSessionContentState`) already paints cached
+ * messages without waiting on the runtime; this is the route-level gate that
+ * used to defeat it by replacing the whole chat before Gate B ever ran.
+ *
+ * The composer stays gated separately: `sessionComposerReadiness` disables
+ * nothing (a submit becomes a durable inbox row the control plane delivers once
+ * the box answers) but shows its own "waking" notice while the runtime is down.
+ * Only the READ path is freed here; SENDING still waits on the runtime,
+ * unchanged.
+ *
+ * A sandbox status outside `'stopped'`/`'error'` — or no cached content —
+ * returns `false`: the terminal card stays exactly as it was, byte for byte.
+ */
+export declare function canRenderCachedTranscriptWhileSandboxDown(state: StoppedSandboxCacheState): boolean;

package/dist/session/status/session-terminal-state.js

@@ -0,0 +1,62 @@
+/**
+ * Detect a terminal `/start` FAILURE that has no serialized sandbox row.
+ *
+ * Read `stage`, never `phase`. `useSession` collapses three unrelated
+ * conditions into `phase === 'error'`: a terminal stage, a typed `/start`
+ * error, AND a transient OpenCode REST error. Deriving "provisioning failed
+ * before allocation" from `phase` therefore fired on states that are not a
+ * provisioning failure at all — a session the server reports as `stopped`, and
+ * a session still booting (`stage: 'starting'`, `sandbox: null`, `retriable:
+ * true`) whose runtime list happened to error. Both painted a terminal
+ * "Couldn't start session" card over a session that had not failed.
+ *
+ * `retriable` is the server's own "polling can still make progress" flag, so an
+ * unfinished boot can never be reported as a dead end even if a future stage
+ * value lands here.
+ */
+export function isUnmaterializedSessionFailure(state) {
+    if (state.hasStartError || state.retriable)
+        return false;
+    if (state.stage !== 'failed')
+        return false;
+    return state.sandboxStatus == null;
+}
+/**
+ * Detect a session the server reports as `stopped` with no serialized sandbox
+ * row (`openSession`'s terminal branch for a `stopped`/`completed` session row).
+ *
+ * It needs its own branch because the page's `fatal` path reads
+ * `sandbox.status`, which is unavailable here — so this state used to fall
+ * through to the unmaterialized-FAILURE card and tell the user a session that
+ * merely stopped had "failed before its computer was created".
+ */
+export function isDormantSessionWithoutRuntime(state) {
+    if (state.hasStartError || state.retriable)
+        return false;
+    if (state.stage !== 'stopped')
+        return false;
+    return state.sandboxStatus == null;
+}
+/**
+ * A `stopped`/`error` sandbox whose session already has renderable cached
+ * content should render the TRANSCRIPT with a calm waking affordance, not the
+ * full-screen restart/waking card `fatal` used to force unconditionally.
+ *
+ * Reading what you already wrote never needs a sandbox — Gate B in
+ * `session-chat.tsx` (`resolveSessionContentState`) already paints cached
+ * messages without waiting on the runtime; this is the route-level gate that
+ * used to defeat it by replacing the whole chat before Gate B ever ran.
+ *
+ * The composer stays gated separately: `sessionComposerReadiness` disables
+ * nothing (a submit becomes a durable inbox row the control plane delivers once
+ * the box answers) but shows its own "waking" notice while the runtime is down.
+ * Only the READ path is freed here; SENDING still waits on the runtime,
+ * unchanged.
+ *
+ * A sandbox status outside `'stopped'`/`'error'` — or no cached content —
+ * returns `false`: the terminal card stays exactly as it was, byte for byte.
+ */
+export function canRenderCachedTranscriptWhileSandboxDown(state) {
+    const sandboxIsDown = state.sandboxStatus === 'stopped' || state.sandboxStatus === 'error';
+    return sandboxIsDown && state.hasCachedContent;
+}

package/dist/session/status/stop-refusal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * In a shared session only the member who started the running turn, the
+ * session owner or a project manager may stop it. The composer hides Stop when
+ * `useSession().canStop` says no, so a refusal only reaches here when that
+ * answer was stale. The server's own words are what the toast says.
+ */
+export declare const NOT_TURN_PROMPTER = "not_turn_prompter";
+/**
+ * The server's message when it refused a stop, or null for any other failure.
+ * A REST stop (the hold, "Stop and send") is an `ApiError` carrying the code.
+ * The runtime abort answers through the sandbox proxy, whose error keeps the
+ * status and the message but not the code, so a 403 counts there too.
+ */
+export declare function stopRefusalMessage(error: unknown): string | null;

package/dist/session/status/stop-refusal.js

@@ -0,0 +1,21 @@
+/**
+ * In a shared session only the member who started the running turn, the
+ * session owner or a project manager may stop it. The composer hides Stop when
+ * `useSession().canStop` says no, so a refusal only reaches here when that
+ * answer was stale. The server's own words are what the toast says.
+ */
+export const NOT_TURN_PROMPTER = 'not_turn_prompter';
+/**
+ * The server's message when it refused a stop, or null for any other failure.
+ * A REST stop (the hold, "Stop and send") is an `ApiError` carrying the code.
+ * The runtime abort answers through the sandbox proxy, whose error keeps the
+ * status and the message but not the code, so a 403 counts there too.
+ */
+export function stopRefusalMessage(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const { status, code, message } = error;
+    if (code !== NOT_TURN_PROMPTER && status !== 403)
+        return null;
+    return typeof message === 'string' && message ? message : null;
+}

package/dist/session/status/use-readiness-settling.d.ts

@@ -0,0 +1,18 @@
+/**
+ * How long a freshly mounted session may say NOTHING about its runtime.
+ *
+ * Long enough to cover the first health probe + `GET .../turn` round trip on a
+ * healthy session (both answer well inside a second locally and on dev), short
+ * enough that a genuinely parked box still announces its wake promptly. The
+ * cost of being wrong in one direction is a false "your session dropped" flash
+ * on every page load; in the other, a real wake notice arrives ~1.5s later.
+ */
+export declare const READINESS_SETTLE_MS = 1500;
+/**
+ * True while the runtime has not been contacted yet AND the mount is young.
+ *
+ * Feeds `sessionComposerReadiness({ settling })`, whose fallback would
+ * otherwise assert "Waking this session up…" the instant a page loads — the
+ * one claim nothing had checked. See that input's docstring.
+ */
+export declare function useReadinessSettling(uncontacted: boolean, windowMs?: number): boolean;