yepanywhere 0.6.0 → 0.6.2

package/dist/routes/sessions.js

@@ -1,4 +1,4 @@
-import { ALL_PERMISSION_MODES, PROMPT_SUGGESTION_MODES, buildEffectiveAgentContext, clampRecapAfterSeconds, getModelContextWindow, isUrlProjectId, isWorkstreamId, mainWorkstreamId, thinkingOptionToConfig, truncateSessionTitle, } from "../../bundled/@yep-anywhere/shared/dist/index.js";
+import { ALL_PERMISSION_MODES, buildEffectiveAgentContext, getModelContextWindow, isUrlProjectId, isWorkstreamId, mainWorkstreamId, truncateSessionTitle, } from "../../bundled/@yep-anywhere/shared/dist/index.js";
 import { randomUUID } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { performance } from "node:perf_hooks";
@@ -6,6 +6,7 @@ import { Hono } from "hono";
 import { augmentTextBlocks } from "../augments/markdown-augments.js";
 import { getLogger } from "../logging/logger.js";
 import { DETACHED_PROJECT_PATH, encodeProjectId } from "../projects/paths.js";
+import { resolveCanonicalProjectRedirect } from "./session-project-routing.js";
 import { ensureRemoteDirectory } from "../sdk/remote-spawn.js";
 import { parseSlashCommandSubmission } from "../sdk/slashCommandEmulation.js";
 import { getProjectDirFromCwd, syncSessions } from "../sdk/session-sync.js";
@@ -16,7 +17,7 @@ import { GrokSessionReader } from "../sessions/grok-reader.js";
 import { extractLastAgentExcerpt } from "../sessions/agent-excerpt.js";
 import { normalizeSession } from "../sessions/normalization.js";
 import { applyRecapOverlayToSession, applyRecapOverlayToSummary, hasEquivalentRecapMessage, hasUnreadProviderContent, latestRecapMessage, mergeRecapMessages, } from "../sessions/recap-overlays.js";
-import { sliceAfterMessageIdWithMatch, sliceAtCompactBoundaries, sliceAtUserTurnBoundary, } from "../sessions/pagination.js";
+import { sliceAfterMessageIdWithMatch, sliceAtCompactAndUserTurnBoundaries, sliceAtCompactBoundaries, sliceAtUserTurnBoundary, } from "../sessions/pagination.js";
 import { augmentTaskListSnapshots, pruneTaskListSnapshotsToLatest, } from "../augments/task-list-augments.js";
 import { augmentEditToolUses, augmentPersistedSessionMessages, } from "../sessions/persisted-augments.js";
 import { findSessionSummaryAcrossProviders, getSessionSources, } from "../sessions/provider-resolution.js";
@@ -26,6 +27,11 @@ import { ResumeCompactionError } from "../supervisor/Supervisor.js";
 import { buildUserMessageMetadata, normalizeOptionalServiceTier, parseHelperSettings, parseOptionalExecutor, parseOptionalResumeMode, } from "./session-request-helpers.js";
 import { resolveCompactPercent, resolveCompactWindow, } from "./session-compact-thresholds.js";
 import { getClaudeResumeBlockerFromReader, } from "./session-claude-resume-guard.js";
+import { isClaudeSdkProviderName, isCodexProviderName, providerResolutionDeps, } from "./session-provider-resolution.js";
+import { parseSessionMetadataPatch } from "./session-metadata-patch.js";
+import { recoveredPatientQueueSummaries, sessionQueueSummaries, } from "./session-queue-summaries.js";
+import { reportableProcessState, resolveRecoveredGroupForDelivery, resumeRecoveredGroup, } from "./session-recovered-queue.js";
+import { buildThinkingOptions } from "./session-thinking-options.js";
 const SESSION_DETAIL_SLOW_LOG_MS = 250;
 const DEFAULT_SESSION_DETAIL_TAIL_COMPACTIONS = 2;
 const LARGE_FULL_HISTORY_MESSAGE_THRESHOLD = 1000;
@@ -40,9 +46,6 @@ async function getSessionSlashCommands(process, provider) {
 function roundedMs(value) {
     return Math.round(value * 10) / 10;
 }
-function isClaudeSdkProviderName(provider) {
-    return provider === "claude" || provider === "claude-ollama";
-}
 /**
  * Type guard to check if a result is a QueuedResponse
  */
@@ -55,111 +58,15 @@ function isQueuedResponse(result) {
 function isQueueFullResponse(result) {
     return "error" in result && result.error === "queue_full";
 }
-function isCodexProviderName(provider) {
-    return provider === "codex" || provider === "codex-oss";
-}
 const AUTO_COMPACT_CONTEXT_PERCENT_THRESHOLD = 85;
 const AUTO_COMPACT_MODEL_PREFIXES = ["gpt-5.3-codex-spark"];
 const AUTO_COMPACT_TARGET_PROVIDERS = new Set([
     "codex",
     "codex-oss",
 ]);
-function providerResolutionDeps(deps) {
-    return {
-        readerFactory: deps.readerFactory,
-        sessionIndexService: deps.sessionIndexService,
-        codexSessionsDir: deps.codexSessionsDir,
-        codexReaderFactory: deps.codexReaderFactory,
-        geminiSessionsDir: deps.geminiSessionsDir,
-        geminiReaderFactory: deps.geminiReaderFactory,
-        geminiHashToCwd: deps.geminiScanner?.getHashToCwd(),
-        grokSessionsDir: deps.grokSessionsDir,
-        grokReaderFactory: deps.grokReaderFactory,
-        piSessionsDir: deps.piSessionsDir,
-        piReaderFactory: deps.piReaderFactory,
-    };
-}
-function persistedPatientQueueSummary(item) {
-    const attachmentCount = (item.message.attachments?.length ?? 0) +
-        (item.message.images?.length ?? 0) +
-        (item.message.documents?.length ?? 0);
-    const tempId = item.message.tempId ?? item.source?.tempId;
-    return {
-        id: item.id,
-        ...(tempId ? { tempId } : {}),
-        content: item.message.text,
-        timestamp: item.queuedAt,
-        ...(item.message.attachments?.length
-            ? { attachments: item.message.attachments }
-            : {}),
-        ...(attachmentCount > 0 ? { attachmentCount } : {}),
-        ...(item.message.metadata ? { metadata: item.message.metadata } : {}),
-        kind: "patient",
-        status: item.status === "paused-after-restart" ? item.status : "queued",
-        sessionId: item.sessionId,
-        projectId: item.projectId,
-        queuedAt: item.queuedAt,
-        createdAt: item.createdAt,
-        updatedAt: item.updatedAt,
-    };
-}
 function isApprovalAuditLogEnabled(deps) {
     return (deps.serverSettingsService?.getSetting("approvalAuditLogEnabled") === true);
 }
-function recoveredPatientQueueSummaries(deps, sessionId) {
-    return recoveredPatientQueueItems(deps, sessionId).map(persistedPatientQueueSummary);
-}
-function recoveredPatientQueueItems(deps, sessionId) {
-    if (!deps.sessionQueuePersistenceService) {
-        return [];
-    }
-    return deps.sessionQueuePersistenceService
-        .listSession(sessionId)
-        .filter((item) => item.kind === "patient" && item.status === "paused-after-restart")
-        .sort((left, right) => left.queuedAt.localeCompare(right.queuedAt));
-}
-function sessionQueueSummaries(deps, sessionId, process) {
-    const recovered = recoveredPatientQueueSummaries(deps, sessionId);
-    if (process && typeof process.getDeferredQueueSummary === "function") {
-        const messages = [
-            ...process.getDeferredQueueSummary(),
-            ...recovered,
-        ];
-        return messages.sort((left, right) => (left.queuedAt ?? left.timestamp).localeCompare(right.queuedAt ?? right.timestamp));
-    }
-    if (process) {
-        return recovered;
-    }
-    return recovered;
-}
-function recoveredPatientUserMessage(item) {
-    const mode = item.message.mode ?? item.mode;
-    const metadata = {
-        ...item.message.metadata,
-        deliveryIntent: "patient",
-    };
-    // Live-queue chip actions (cancel, steer) address entries by tempId, so a
-    // recovered entry that was persisted without one gets a stable fallback.
-    const tempId = item.message.tempId ?? item.source?.tempId ?? `recovered-${item.id}`;
-    return {
-        ...item.message,
-        tempId,
-        ...(mode ? { mode } : {}),
-        metadata,
-    };
-}
-/**
- * Count live patient queue entries composed after the given recovered entry.
- * Resuming or steering the recovered entry would deliver its older content
- * behind these newer ones, so callers reject while any exist. Regular
- * deferred entries never block recovered work: the regular lane delivers on
- * turn boundaries and may pass patient work by design.
- */
-function livePatientEntriesNewerThan(process, queuedAt) {
-    const live = process?.getDeferredQueueSummary() ?? [];
-    return live.filter((entry) => entry.metadata?.deliveryIntent === "patient" &&
-        entry.timestamp.localeCompare(queuedAt) > 0).length;
-}
 async function resolveSessionReaderForAgentContent({ deps, project, sessionId, projectId, }) {
     const metadataProvider = deps.sessionMetadataService?.getProvider(sessionId);
     const resolved = await findSessionSummaryAcrossProviders(project, sessionId, projectId, providerResolutionDeps(deps), metadataProvider, { readMode: "head" });
@@ -701,6 +608,7 @@ function isCompactSummaryUserMessage(message) {
 }
 function isUserAuthoredRequest(message) {
     return (isHumanUserMessage(message) &&
+        message.isSynthetic !== true &&
         !isCompactSummaryUserMessage(message) &&
         !isSlashCommandSkillBodyUserMessage(message));
 }
@@ -1132,30 +1040,43 @@ export function createSessionsRoutes(deps) {
     };
     const resolveSessionProjectRouting = async (requestProjectId, sessionId) => {
         const workingProjectId = deps.sessionMetadataService?.getMetadata(sessionId)?.workingProjectId;
-        if (workingProjectId && workingProjectId !== requestProjectId) {
-            return { redirectProjectId: workingProjectId };
-        }
         const activeProcess = deps.supervisor.getProcessForSession(sessionId);
-        if (activeProcess &&
-            typeof activeProcess.projectId === "string" &&
-            isUrlProjectId(activeProcess.projectId) &&
-            activeProcess.projectId !== requestProjectId) {
-            return { redirectProjectId: activeProcess.projectId };
+        const redirectProjectId = resolveCanonicalProjectRedirect({
+            requestProjectId,
+            workingProjectId,
+            activeProcessProjectId: typeof activeProcess?.projectId === "string"
+                ? activeProcess.projectId
+                : undefined,
+        });
+        if (redirectProjectId) {
+            return { redirectProjectId };
         }
         const workingProject = await deps.scanner.getOrCreateProject(requestProjectId);
         if (!workingProject) {
             return { error: "Project not found", status: 404 };
         }
         const metadata = deps.sessionMetadataService?.getMetadata(sessionId);
-        const transcriptProjectId = metadata?.workingProjectId === requestProjectId &&
-            metadata.transcriptProjectId
+        const overlayTranscriptProjectId = metadata?.workingProjectId === requestProjectId &&
+            metadata.transcriptProjectId &&
+            metadata.transcriptProjectId !== requestProjectId
             ? metadata.transcriptProjectId
-            : requestProjectId;
-        const transcriptProject = transcriptProjectId === requestProjectId
-            ? workingProject
-            : await deps.scanner.getOrCreateProject(transcriptProjectId);
-        if (!transcriptProject) {
-            return { error: "Transcript project not found", status: 404 };
+            : undefined;
+        // Default: the transcript lives under the working (request) project.
+        let transcriptProjectId = requestProjectId;
+        let transcriptProject = workingProject;
+        // Overlay case (session "moved" to a different working project): the
+        // transcript may live under a distinct project. Trust the recorded pointer
+        // only if the transcript is actually findable there — a stale/wrong pointer
+        // must not permanently brick viewing, so fall back to the working project.
+        if (overlayTranscriptProjectId) {
+            const overlayProject = await deps.scanner.getOrCreateProject(overlayTranscriptProjectId);
+            const overlayHasTranscript = overlayProject
+                ? Boolean(await findSessionSummaryAcrossProviders(overlayProject, sessionId, overlayTranscriptProjectId, providerResolutionDeps(deps), deps.sessionMetadataService?.getProvider(sessionId), { readMode: "head" }))
+                : false;
+            if (overlayProject && overlayHasTranscript) {
+                transcriptProjectId = overlayTranscriptProjectId;
+                transcriptProject = overlayProject;
+            }
         }
         return {
             transcriptProject,
@@ -1425,7 +1346,9 @@ export function createSessionsRoutes(deps) {
         const lastSeenAt = lastSeenEntry?.timestamp;
         // Get pending input request from active process
         const pendingInputRequest = process?.state.type === "waiting-input" ? process.state.request : null;
-        const providerRuntimeStatus = process?.getProviderRuntimeStatus() ?? null;
+        const providerRuntimeStatus = deps.supervisor.getProviderRuntimeStatusForSession?.(sessionId) ??
+            process?.getProviderRuntimeStatus() ??
+            null;
         // Read minimal session info from disk (just for title/timestamps, no messages)
         const metadataProvider = metadata?.provider ??
             deps.sessionMetadataService?.getProvider(sessionId);
@@ -1617,9 +1540,9 @@ export function createSessionsRoutes(deps) {
     //   ?afterMessageId=<id> - incremental forward-fetch (append new messages)
     //   ?tailCompactions=<n> - return only last N compact boundaries worth of messages
     //   ?beforeMessageId=<id> - cursor for loading older chunks (used with tailCompactions)
-    //   ?tailTurns=<n> - aggressive opt-in client memory cap by recent user turns
-    //   ?tailFrom=<id> - aggressive opt-in client memory cap from a user message id
-    //   ?fullHistory=1 - explicit opt-in to the full transcript
+    //   ?tailTurns=<n> - recent-turn selector within the authorized history scope
+    //   ?tailFrom=<id> - start selector within the authorized history scope
+    //   ?fullHistory=1 - explicitly authorize selectors to inspect full history
     routes.get("/projects/:projectId/sessions/:sessionId", async (c) => {
         const requestStartMs = performance.now();
         const projectId = c.req.param("projectId");
@@ -1648,9 +1571,10 @@ export function createSessionsRoutes(deps) {
             : undefined;
         const defaultedToCompactTail = !fullHistory &&
             !afterMessageId &&
-            !tailFrom &&
-            requestedTailTurns === undefined &&
             requestedTailCompactions === undefined;
+        const unboundedRequestDefaultedToCompactTail = defaultedToCompactTail &&
+            !tailFrom &&
+            requestedTailTurns === undefined;
         const effectiveTailCompactions = requestedTailCompactions ??
             (defaultedToCompactTail
                 ? DEFAULT_SESSION_DETAIL_TAIL_COMPACTIONS
@@ -1724,7 +1648,9 @@ export function createSessionsRoutes(deps) {
         // Get pending input request from active process (for tool approval prompts)
         // This ensures clients get pending requests immediately without waiting for SSE
         const pendingInputRequest = process?.state.type === "waiting-input" ? process.state.request : null;
-        const providerRuntimeStatus = process?.getProviderRuntimeStatus() ?? null;
+        const providerRuntimeStatus = deps.supervisor.getProviderRuntimeStatusForSession?.(sessionId) ??
+            process?.getProviderRuntimeStatus() ??
+            null;
         // Get available slash commands (for "/" button and typed slash menu)
         // The init message that normally carries these gets discarded from the SSE buffer
         // after ~30s, so we attach them to the REST response. Providers with known
@@ -1812,12 +1738,21 @@ export function createSessionsRoutes(deps) {
         // Get notification data (lastSeenAt, hasUnread)
         const lastSeenEntry = deps.notificationService?.getLastSeen(sessionId);
         const lastSeenAt = lastSeenEntry?.timestamp;
-        // Apply pagination if requested (BEFORE expensive augmentation). tailTurns
-        // is an opt-in stronger client memory cap, so it wins over compact tails.
-        // Skip both when afterMessageId is present since that's an incremental
-        // forward-fetch use case.
+        // Apply pagination BEFORE expensive augmentation. Compact boundaries set
+        // the authorized history scope by default; turn selectors may narrow that
+        // scope but cannot broaden it unless fullHistory=1 removed the default.
+        // Skip initial-window slicing for incremental forward fetches.
         let paginationInfo;
         if (!afterMessageId &&
+            effectiveTailCompactions !== undefined &&
+            !beforeMessageId &&
+            (tailFrom || requestedTailTurns !== undefined)) {
+            const sliced = sliceAtCompactAndUserTurnBoundaries(session.messages, effectiveTailCompactions, requestedTailTurns ?? 20, tailFrom);
+            session = { ...session, messages: sliced.messages };
+            paginationInfo = sliced.pagination;
+        }
+        else if (!afterMessageId &&
+            effectiveTailCompactions === undefined &&
             (tailFrom || requestedTailTurns !== undefined)) {
             const sliced = sliceAtUserTurnBoundary(session.messages, requestedTailTurns ?? 20, tailFrom);
             session = { ...session, messages: sliced.messages };
@@ -1889,7 +1824,7 @@ export function createSessionsRoutes(deps) {
         }
         const { messages: _messages, ...sessionMetadata } = session;
         const totalMs = performance.now() - requestStartMs;
-        if (defaultedToCompactTail &&
+        if (unboundedRequestDefaultedToCompactTail &&
             normalizedMessageCount >= LARGE_FULL_HISTORY_MESSAGE_THRESHOLD) {
             getLogger().warn({
                 beforeMessageId: beforeMessageId ?? null,
@@ -2048,10 +1983,7 @@ export function createSessionsRoutes(deps) {
             tempId: body.tempId,
             metadata: buildUserMessageMetadata(body, serverTimestamp, "direct"),
         };
-        // Convert thinking option to SDK config
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         // Convert model option (undefined or "default" means use CLI default)
         const model = body.model && body.model !== "default" ? body.model : undefined;
         const serviceTier = normalizeOptionalServiceTier(body.serviceTier);
@@ -2130,10 +2062,7 @@ export function createSessionsRoutes(deps) {
         if ("error" in workstreamTarget) {
             return c.json({ error: workstreamTarget.error }, workstreamTarget.status);
         }
-        // Convert thinking option to SDK config
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         // Convert model option (undefined or "default" means use CLI default)
         const model = body.model && body.model !== "default" ? body.model : undefined;
         const serviceTier = normalizeOptionalServiceTier(body.serviceTier);
@@ -2204,9 +2133,7 @@ export function createSessionsRoutes(deps) {
             tempId: body.tempId,
             metadata: buildUserMessageMetadata(body, serverTimestamp, "direct"),
         };
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         const model = body.model && body.model !== "default" ? body.model : undefined;
         const serviceTier = normalizeOptionalServiceTier(body.serviceTier);
         const result = await deps.supervisor.startSession(projectPath, userMessage, body.mode, {
@@ -2258,9 +2185,7 @@ export function createSessionsRoutes(deps) {
             return c.json({ error: helperSettings.error }, 400);
         }
         const projectPath = await ensureDetachedProjectPath(executor);
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         const model = body.model && body.model !== "default" ? body.model : undefined;
         const serviceTier = normalizeOptionalServiceTier(body.serviceTier);
         const result = await deps.supervisor.createSession(projectPath, body.mode, {
@@ -2340,10 +2265,7 @@ export function createSessionsRoutes(deps) {
             tempId: body.tempId,
             metadata: buildUserMessageMetadata(body, serverTimestamp, "direct"),
         };
-        // Convert thinking option to SDK config
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         // Convert model option (undefined or "default" means use CLI default). When
         // the client sends no model (e.g. resume after a server restart), recover the
         // YA model id persisted at launch so the process keeps its requested alias
@@ -2578,9 +2500,7 @@ export function createSessionsRoutes(deps) {
             ? body.model
             : metadata?.requestedModel;
         const model = rawModel && rawModel !== "default" ? rawModel : undefined;
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         let process;
         try {
             process = await deps.supervisor.reactivateSession(project.path, sessionId, body.mode, {
@@ -2742,9 +2662,7 @@ export function createSessionsRoutes(deps) {
         const sourceProvider = sourceSession.provider ?? preferredSourceProvider;
         const providerName = body.provider ?? sourceProvider;
         const originalMetadata = deps.sessionMetadataService?.getMetadata(sessionId);
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         const model = body.model && body.model !== "default" ? body.model : undefined;
         const serviceTier = normalizeOptionalServiceTier(body.serviceTier);
         if (restartMode === "fork") {
@@ -3569,10 +3487,7 @@ export function createSessionsRoutes(deps) {
                 serverTimestamp,
             });
         }
-        // Convert thinking option to SDK config
-        const { thinking, effort } = body.thinking
-            ? thinkingOptionToConfig(body.thinking, body.showThinking)
-            : { thinking: undefined, effort: undefined };
+        const { thinking, effort } = buildThinkingOptions(body);
         const metadataProvider = deps.sessionMetadataService?.getProvider(sessionId);
         const metadataExecutor = parseOptionalExecutor(deps.sessionMetadataService?.getExecutor(sessionId));
         if (metadataExecutor.error) {
@@ -3656,131 +3571,12 @@ export function createSessionsRoutes(deps) {
             deferredMessages: recoveredPatientQueueSummaries(deps, sessionId),
         });
     });
-    // A recovered patient queue entry may need a fresh process before it can
-    // rejoin the live queue. Shared by the recovered-queue resume/steer routes.
-    const ensureProcessForRecoveredItem = async (sessionId, item, existing) => {
-        let process = existing;
-        const mode = item.message.mode ?? item.mode;
-        const metadata = deps.sessionMetadataService?.getMetadata(sessionId);
-        const parsedExecutor = parseOptionalExecutor(item.executor ?? metadata?.executor);
-        if (parsedExecutor.error) {
-            return { error: parsedExecutor.error, status: 400 };
-        }
-        const rawModel = item.model ?? metadata?.requestedModel;
-        const model = rawModel && rawModel !== "default" ? rawModel : undefined;
-        if (!process) {
-            try {
-                process = await deps.supervisor.reactivateSession(item.projectPath, sessionId, mode, {
-                    model,
-                    serviceTier: item.serviceTier,
-                    providerName: item.provider,
-                    executor: parsedExecutor.executor,
-                    globalInstructions: getGlobalInstructions(),
-                    recapAfterSeconds: metadata?.recapAfterSeconds,
-                    promptSuggestionMode: metadata?.promptSuggestionMode,
-                });
-            }
-            catch (error) {
-                return {
-                    error: error instanceof Error
-                        ? error.message
-                        : "Failed to reactivate session",
-                    status: 503,
-                };
-            }
-            await persistLaunchMetadata(sessionId, item.provider, parsedExecutor.executor, undefined, item.model ?? metadata?.requestedModel, metadata?.promptSuggestionMode, metadata?.recapAfterSeconds);
-        }
-        else if (mode) {
-            process.setPermissionMode(mode);
-        }
-        return { process };
-    };
-    // Move recovered entries back into the live patient queue in queuedAt
-    // order. On a mid-group failure the earlier resumes stand; the caller
-    // reports the failed entry.
-    const resumeRecoveredGroup = async (process, group, options) => {
-        let last;
-        let lastMessage;
-        for (const item of group) {
-            const userMessage = recoveredPatientUserMessage(item);
-            await process.primeSupportedCommandsForMessage(userMessage);
-            const result = process.deferMessage(userMessage, {
-                promoteIfReady: options.promoteIfReady,
-                persistedQueueId: item.id,
-                timestamp: item.queuedAt,
-            });
-            if (!result.success) {
-                return {
-                    last,
-                    lastMessage,
-                    error: result.error ?? "Failed to queue message",
-                };
-            }
-            last = result;
-            lastMessage = userMessage;
-        }
-        return { last, lastMessage };
-    };
-    const reportableProcessState = (process) => process.state.type === "waiting-input" || process.state.type === "in-turn"
-        ? process.state.type
-        : "idle";
-    // Shared prologue for the recovered-queue resume/steer routes: resolve the
-    // target and the recovered group composed before it, refuse while newer
-    // live patient entries exist, and ensure a live process. The newer-entries
-    // guard runs again after the ensure — its await is a window for new
-    // arrivals, and recovered context must never jump a newer patient entry.
-    const resolveRecoveredGroupForDelivery = async (sessionId, queueId, refusal) => {
-        if (!deps.sessionQueuePersistenceService) {
-            return {
-                ok: false,
-                status: 503,
-                body: { error: "Session queue persistence unavailable" },
-            };
-        }
-        const recoveredItems = recoveredPatientQueueItems(deps, sessionId);
-        const targetIndex = recoveredItems.findIndex((candidate) => candidate.id === queueId);
-        const target = recoveredItems[targetIndex];
-        if (!target) {
-            return {
-                ok: false,
-                status: 404,
-                body: { error: "Recovered queued message not found" },
-            };
-        }
-        const group = recoveredItems.slice(0, targetIndex + 1);
-        let process = deps.supervisor.getProcessForSession(sessionId);
-        if (process?.isTerminated) {
-            process = undefined;
-        }
-        const refuseIfNewerEntries = (candidate) => livePatientEntriesNewerThan(candidate, target.queuedAt) > 0
-            ? {
-                ok: false,
-                status: 409,
-                body: {
-                    error: refusal,
-                    headQueueId: target.id,
-                    deferredMessages: sessionQueueSummaries(deps, sessionId, candidate),
-                },
-            }
-            : null;
-        const refusedBefore = refuseIfNewerEntries(process);
-        if (refusedBefore) {
-            return refusedBefore;
-        }
-        const ensured = await ensureProcessForRecoveredItem(sessionId, target, process);
-        if ("error" in ensured) {
-            return {
-                ok: false,
-                status: ensured.status,
-                body: { error: ensured.error },
-            };
-        }
-        process = ensured.process;
-        const refusedAfter = refuseIfNewerEntries(process);
-        if (refusedAfter) {
-            return refusedAfter;
-        }
-        return { ok: true, process, group };
+    const recoveredQueueDeps = {
+        sessionQueuePersistenceService: deps.sessionQueuePersistenceService,
+        sessionMetadataService: deps.sessionMetadataService,
+        supervisor: deps.supervisor,
+        getGlobalInstructions,
+        persistLaunchMetadata,
     };
     // POST /api/sessions/:sessionId/recovered-queue/:queueId/resume - Move
     // restart-paused patient queue entries back into the live patient queue,
@@ -3789,7 +3585,7 @@ export function createSessionsRoutes(deps) {
     routes.post("/sessions/:sessionId/recovered-queue/:queueId/resume", async (c) => {
         const sessionId = c.req.param("sessionId");
         const queueId = c.req.param("queueId");
-        const resolved = await resolveRecoveredGroupForDelivery(sessionId, queueId, "Drain or cancel newer queued messages before resuming recovered work.");
+        const resolved = await resolveRecoveredGroupForDelivery(recoveredQueueDeps, sessionId, queueId, "Drain or cancel newer queued messages before resuming recovered work.");
         if (!resolved.ok) {
             return c.json(resolved.body, resolved.status);
         }
@@ -3827,7 +3623,7 @@ export function createSessionsRoutes(deps) {
     routes.post("/sessions/:sessionId/recovered-queue/:queueId/steer", async (c) => {
         const sessionId = c.req.param("sessionId");
         const queueId = c.req.param("queueId");
-        const resolved = await resolveRecoveredGroupForDelivery(sessionId, queueId, "Drain or cancel newer queued messages before steering recovered work.");
+        const resolved = await resolveRecoveredGroupForDelivery(recoveredQueueDeps, sessionId, queueId, "Drain or cancel newer queued messages before steering recovered work.");
         if (!resolved.ok) {
             return c.json(resolved.body, resolved.status);
         }
@@ -3875,6 +3671,21 @@ export function createSessionsRoutes(deps) {
         await process.waitForPatientQueuePersistenceIdle();
         return c.json({ cancelled: true });
     });
+    // DELETE /api/sessions/:sessionId/steering/:tempId - Cancel a sent steering
+    // message that has not yet been consumed by the provider.
+    routes.delete("/sessions/:sessionId/steering/:tempId", async (c) => {
+        const sessionId = c.req.param("sessionId");
+        const tempId = c.req.param("tempId");
+        const process = deps.supervisor.getProcessForSession(sessionId);
+        if (!process) {
+            return c.json({ error: "No active process for session" }, 404);
+        }
+        const cancelled = process.cancelUnconfirmedSteerMessage(tempId);
+        if (!cancelled) {
+            return c.json({ error: "Steering message already acted on or not found" }, 404);
+        }
+        return c.json({ cancelled: true });
+    });
     // POST /api/sessions/:sessionId/deferred/:tempId/steer - Steer a patient
     // queued message, and every patient entry ahead of it, into the session now.
     routes.post("/sessions/:sessionId/deferred/:tempId/steer", async (c) => {
@@ -4116,137 +3927,27 @@ export function createSessionsRoutes(deps) {
         catch {
             return c.json({ error: "Invalid JSON body" }, 400);
         }
-        // At least one field must be provided
-        if (body.title === undefined &&
-            body.archived === undefined &&
-            body.starred === undefined &&
-            body.parentSessionId === undefined &&
-            body.heartbeatTurnsEnabled === undefined &&
-            body.heartbeatTurnsAfterMinutes === undefined &&
-            body.heartbeatTurnText === undefined &&
-            body.heartbeatForceAfterMinutes === undefined &&
-            body.promptSuggestionMode === undefined &&
-            body.recapAfterSeconds === undefined) {
-            return c.json({
-                error: "At least one session metadata field must be provided",
-            }, 400);
-        }
-        let heartbeatForceAfterMinutes;
-        if (body.heartbeatForceAfterMinutes !== undefined) {
-            if (body.heartbeatForceAfterMinutes === null ||
-                body.heartbeatForceAfterMinutes === 0) {
-                heartbeatForceAfterMinutes = null;
-            }
-            else if (typeof body.heartbeatForceAfterMinutes === "number" &&
-                Number.isInteger(body.heartbeatForceAfterMinutes) &&
-                body.heartbeatForceAfterMinutes >= 1 &&
-                body.heartbeatForceAfterMinutes <= 1440) {
-                heartbeatForceAfterMinutes = body.heartbeatForceAfterMinutes;
-            }
-            else {
-                return c.json({
-                    error: "heartbeatForceAfterMinutes must be null or an integer between 1 and 1440",
-                }, 400);
-            }
-        }
-        let heartbeatTurnsAfterMinutes;
-        if (body.heartbeatTurnsAfterMinutes !== undefined) {
-            if (body.heartbeatTurnsAfterMinutes === null ||
-                body.heartbeatTurnsAfterMinutes === 0) {
-                heartbeatTurnsAfterMinutes = null;
-            }
-            else if (typeof body.heartbeatTurnsAfterMinutes === "number" &&
-                Number.isInteger(body.heartbeatTurnsAfterMinutes) &&
-                body.heartbeatTurnsAfterMinutes >= 1 &&
-                body.heartbeatTurnsAfterMinutes <= 1440) {
-                heartbeatTurnsAfterMinutes = body.heartbeatTurnsAfterMinutes;
-            }
-            else {
-                return c.json({
-                    error: "heartbeatTurnsAfterMinutes must be null or an integer between 1 and 1440",
-                }, 400);
-            }
-        }
-        const heartbeatTurnText = body.heartbeatTurnText === undefined
-            ? undefined
-            : body.heartbeatTurnText === null || body.heartbeatTurnText === ""
-                ? null
-                : typeof body.heartbeatTurnText === "string"
-                    ? body.heartbeatTurnText.slice(0, 200)
-                    : null;
-        if (body.heartbeatTurnText !== undefined &&
-            body.heartbeatTurnText !== null &&
-            body.heartbeatTurnText !== "" &&
-            typeof body.heartbeatTurnText !== "string") {
-            return c.json({ error: "heartbeatTurnText must be a string or null" }, 400);
-        }
-        if (body.parentSessionId !== undefined &&
-            body.parentSessionId !== null &&
-            typeof body.parentSessionId !== "string") {
-            return c.json({ error: "parentSessionId must be a string or null" }, 400);
-        }
-        const parentSessionId = body.parentSessionId === undefined
-            ? undefined
-            : typeof body.parentSessionId === "string"
-                ? body.parentSessionId.trim() || null
-                : null;
-        // promptSuggestionMode: null/"" clears the preference (revert to default);
-        // a valid enum value is stored; any other value is rejected.
-        let promptSuggestionMode;
-        if (body.promptSuggestionMode !== undefined) {
-            if (body.promptSuggestionMode === null ||
-                body.promptSuggestionMode === "") {
-                promptSuggestionMode = null;
-            }
-            else if (typeof body.promptSuggestionMode === "string" &&
-                PROMPT_SUGGESTION_MODES.includes(body.promptSuggestionMode)) {
-                promptSuggestionMode =
-                    body.promptSuggestionMode;
-            }
-            else {
-                return c.json({ error: "promptSuggestionMode must be one of: off, native" }, 400);
-            }
+        const parsed = parseSessionMetadataPatch(body);
+        if (!parsed.ok) {
+            return c.json({ error: parsed.error }, parsed.status);
         }
-        let recapAfterSeconds;
-        if (body.recapAfterSeconds !== undefined) {
-            if (body.recapAfterSeconds === null || body.recapAfterSeconds === "") {
-                recapAfterSeconds = null;
-            }
-            else if (typeof body.recapAfterSeconds === "number" &&
-                Number.isFinite(body.recapAfterSeconds)) {
-                recapAfterSeconds = clampRecapAfterSeconds(body.recapAfterSeconds);
-            }
-            else {
-                return c.json({ error: "recapAfterSeconds must be null or a finite number" }, 400);
-            }
-        }
-        await deps.sessionMetadataService.updateMetadata(sessionId, {
-            title: body.title,
-            archived: body.archived,
-            starred: body.starred,
-            parentSessionId,
-            heartbeatTurnsEnabled: body.heartbeatTurnsEnabled,
-            heartbeatTurnsAfterMinutes,
-            heartbeatTurnText,
-            heartbeatForceAfterMinutes,
-            promptSuggestionMode,
-            recapAfterSeconds,
-        });
+        const { patch } = parsed;
+        await deps.sessionMetadataService.updateMetadata(sessionId, patch);
         // Emit SSE event so sidebar and other clients can update
         if (deps.eventBus) {
             deps.eventBus.emit({
                 type: "session-metadata-changed",
                 sessionId,
-                title: body.title,
-                archived: body.archived,
-                starred: body.starred,
-                parentSessionId,
-                heartbeatTurnsEnabled: body.heartbeatTurnsEnabled,
-                heartbeatTurnsAfterMinutes,
-                heartbeatTurnText,
-                heartbeatForceAfterMinutes,
-                promptSuggestionMode: promptSuggestionMode ?? undefined,
-                recapAfterSeconds: recapAfterSeconds ?? undefined,
+                title: patch.title,
+                archived: patch.archived,
+                starred: patch.starred,
+                parentSessionId: patch.parentSessionId,
+                heartbeatTurnsEnabled: patch.heartbeatTurnsEnabled,
+                heartbeatTurnsAfterMinutes: patch.heartbeatTurnsAfterMinutes,
+                heartbeatTurnText: patch.heartbeatTurnText,
+                heartbeatForceAfterMinutes: patch.heartbeatForceAfterMinutes,
+                promptSuggestionMode: patch.promptSuggestionMode ?? undefined,
+                recapAfterSeconds: patch.recapAfterSeconds ?? undefined,
                 timestamp: new Date().toISOString(),
             });
         }