@loicngr/kobo 1.11.44 → 1.11.45

package/AGENTS.md

@@ -264,10 +264,48 @@ Background: the engine was migrated from `@openai/codex-sdk` (one-shot `codex ex
 
 ## Workspace operations
 
+### Fresh sessions and LLM handoffs
+
+`session-handoff-service.ts` owns manual transfers within a workspace, including
+same-engine model changes. `session_handoffs` (migration v46) preserves the source,
+target, request idempotency, report and operation state. Lifecycle reservations
+permit only launches carrying their owner token; ordinary chat, reviews and
+automatic writers remain excluded until completion or explicit cancellation.
+
+Stop the source immediately and confirm closure before resuming its exact native
+conversation for the optional report-only turn. The final destination always uses
+a fresh conversation. Generation uses a scoped `submit_session_handoff` MCP tool;
+the backend persists the report, publishes `.ai/handoffs/` documents and owns the
+transition. Never treat this generation as auto-loop progress or settle uncertain
+instructions through it. Pending instruction contents stay with the loop dispatcher.
+
+`EngineProcess.ready`, when provided, confirms initial native session/turn
+acceptance. A returned process handle alone is insufficient evidence that a
+transfer started successfully. Startup reconciliation retains interrupted transfers
+for an explicit retry/skip/cancel decision and never replays them automatically.
+Stop cancels pending transfers, including while no engine is running. Preserve
+source selection by last use after a review return; loading a historical completed
+transfer must not change the user's currently selected conversation.
+Failed, interrupted and cancelled transfers restore the source conversation as well
+as its configuration once the engine is stopped. `agent_sessions.activation_order`
+(migration v47) records starts, resumes and source restoration independently of real
+start/end timestamps. Backend current-session and implicit-resume selection, and the
+client's current-session helper, use this order with the legacy timestamp fallback.
+Keep failed target sessions in history and do not force a historical handoff's
+selection over a later conversation after reload.
+Rolled-back targets have `activation_order = -1`: exclude them from default
+selection and implicit resume, but retain their native id and execution history.
+An explicit start/resume activates them again. Without a source conversation,
+rollback clears the client selection, including stale persisted preferences,
+so the next ordinary message starts a fresh conversation on the restored engine.
+Pending wakeups pinned to the source move to the destination only after confirmed
+startup, in the same transaction as handoff completion. Preserve their prompt and
+deadline, and never rebind a wakeup belonging to another conversation.
+
 ### Review LLM and return to the original session
 
-The current conversation is the running session, or the last used session by
-`max(startedAt, endedAt)` after it stops. Keep the session list in creation order,
+The current conversation is the running session, or the last activated session,
+falling back to `max(startedAt, endedAt)` for legacy rows. Keep the session list in creation order,
 but do not use its first entry to identify the current conversation: a temporary
 review can return to an older session. The stale-session banner and the next
 review's return target must recognize that original session, including on reload.

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to Kōbō are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/). Each release is an `## <version>`
 section — the in-app "What's new" dialog reads this file.
 
+## 1.11.45
+
+- fix(sessions): harden handoff recovery and highlight transfer progress
+- feat(sessions): add fresh sessions with optional handoffs
+
 ## 1.11.44
 
 - chore(deps): update packages and node to 24.21.0

package/README.md

@@ -17,7 +17,7 @@ Kōbō (工房, "workshop") turns *one agent, one terminal* into a real workflow
 
 | | |
 |---|---|
-| **🗂️ Isolated worktrees, two engines** | Every workspace is its own git worktree and branch — parallel sessions never collide. Pick Claude Code or OpenAI Codex per workspace, and switch engines later without losing the worktree: Kōbō hands off tasks, git state, and recent context to a fresh session. |
+| **🗂️ Isolated worktrees, two engines** | Every workspace is its own git worktree and branch — parallel sessions never collide. Pick Claude Code or OpenAI Codex per workspace, and [continue in a fresh session](#fresh-sessions-and-llm-handoffs) with the same LLM or a different model/engine, preserving the worktree and mission history. |
 | **💬 Live chat, real diff review** | Streaming responses, inline Edit/Write diffs, a reasoning panel, and a Monaco diff viewer with **inline file editing**, conflict resolution, and one-click `Sync` / `Push` / `Open PR` / `Merge`. |
 | **🔁 Auto-loop, cron, wakeups** | Turn an agent loose on the task list: it works through tasks, retries on rate limits, and stops itself when there's nothing left, progress stalls, or it needs you. Cron schedules and one-shot wakeups keep workspaces moving on their own timeline. |
 | **🔀 Create from a PR/MR, or from a ticket** | Pick an open pull/merge request from GitHub, GitLab, or Bitbucket and Kōbō resolves every local conflict for you before spinning up the workspace. Or start straight from a Notion page or a Sentry issue URL. |
@@ -62,6 +62,18 @@ Kōbō's production build is an installable PWA — use your browser's **Install
 - **Observability**: a per-session timeline (duration, tools, tokens, errors) and a downloadable redacted diagnostic JSON.
 - **Optional integrations**: Notion (import missions) and Sentry (fix from issue URL), each independently toggled with a **Test connection** action; local voice transcription via `whisper.cpp`.
 
+## Fresh sessions and LLM handoffs
+
+Long conversation getting crowded? Use **Continue in a fresh session** at the bottom of the right-hand Tools panel. **Change LLM** uses the same transfer flow and also lets you select another model within the current engine.
+
+1. Choose the destination model, reasoning effort and permission mode. A fresh session starts with the workspace's current configuration selected.
+2. Leave **Generate a handoff with the current agent** enabled to have the current conversation summarize the objective, constraints, decisions, verified progress, failed approaches and next action. Disable it when the old provider has no quota left: Kōbō builds context from the mission, tasks, Git state and source history without calling that LLM.
+3. Start the transfer. Kōbō interrupts the current work immediately, waits for confirmed shutdown, prepares the handoff and opens a fresh native conversation that continues the mission automatically.
+
+The workspace, worktree, task list and conversation history remain available. The transfer links to its source session and a Markdown report in **Documents** (`.ai/handoffs/`, ignored by Git). Auto-loop keeps its intent and diagnostic budget; queued instructions retain their delivery state. Pending wakeups from the source conversation follow the fresh session once its startup is confirmed.
+
+If generation fails, choose **Retry**, **Continue without an LLM summary**, or **Cancel transfer**. Cancel and Stop leave the work stopped and restore the source conversation and LLM configuration, including when the destination failed to start. Failed attempts remain in history without being resumed automatically. If there was no source conversation, the next message starts a fresh one. A server restart preserves the transfer and report for an explicit recovery decision; it never automatically replays a potentially delivered prompt. Transfers are manual—conversation size does not trigger them automatically.
+
 ## Configuration
 
 The most common knobs:

package/dist/mcp-server/kobo-tasks-handlers.js

@@ -1,3 +1,5 @@
+import { DOCUMENT_DIRS } from '../shared/document-roots.js';
+export { DOCUMENT_DIRS } from '../shared/document-roots.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
@@ -267,7 +269,6 @@ export function getTicketSourcesHandler(worktreePath) {
 }
 // ── Documents ────────────────────────────────────────────────────────────────
 /** Directories (relative to the worktree root) scanned for AI-generated docs. */
-export const DOCUMENT_DIRS = ['docs/plans', 'docs/superpowers', '.ai/thoughts'];
 /** Depth cap to keep recursion bounded even on pathological symlink loops. */
 const DOC_MAX_DEPTH = 8;
 const DOC_MAX_FILE_BYTES = 1024 * 1024;

package/dist/mcp-server/kobo-tasks-server.js

@@ -6,6 +6,8 @@ import { getDb } from '../server/db/index.js';
 import { WORKSPACE_DIALOGUE_TOOLS } from '../shared/workspace-dialogue-tools.js';
 import { createTaskHandler, cronListHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getTicketSourcesHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, listWorkspacesHandler, logThoughtHandler, markAutoLoopReadyHandler, markTaskDoneHandler, readDocumentHandler, readWorkspaceEventsCsvHandler, setWorkspaceAgentDescriptionHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
 import { callWorkspaceDialogueTool } from './workspace-dialogue-client.js';
+const handoffId = process.env.KOBO_HANDOFF_ID;
+const handoffToken = process.env.KOBO_HANDOFF_TOKEN;
 const workspaceId = process.env.KOBO_WORKSPACE_ID;
 const dbPath = process.env.KOBO_DB_PATH;
 const settingsPath = process.env.KOBO_SETTINGS_PATH;
@@ -146,6 +148,16 @@ const TASK_ORDER_PROPERTIES = {
     },
 };
 const WORKSPACE_SCOPED_TOOLS = [
+    {
+        name: 'submit_session_handoff',
+        description: 'Submit the final Markdown handoff requested by Kōbō for this generation turn, then end your turn. Only available during a backend-owned session transfer; does not launch or stop sessions.',
+        inputSchema: {
+            type: 'object',
+            properties: { report: { type: 'string', minLength: 1, maxLength: 24000 } },
+            required: ['report'],
+        },
+        annotations: { destructiveHint: false, openWorldHint: false },
+    },
     {
         name: 'list_tasks',
         description: 'CALL FIRST on any non-trivial turn to know what the user wants done and what is already completed. Returns every task and acceptance criterion for the current workspace with its id, status, sort_order, role, and verification evidence. Re-call periodically (before marking something done, or after the user asks for a status) to stay in sync with user-added or external updates.',
@@ -412,13 +424,13 @@ const WORKSPACE_SCOPED_TOOLS = [
     // ── Knowledge / context tools ─────────────────────────────────────────────
     {
         name: 'list_documents',
-        description: 'CALL EARLY on a new session to discover plans, specs, and thoughts previously written for this workspace. Recursively lists every .md under docs/plans/, docs/superpowers/, and .ai/thoughts/. Before writing a new plan, check if one already exists.',
+        description: 'CALL EARLY on a new session to discover plans, specs, and thoughts previously written for this workspace. Recursively lists every .md under docs/plans/, docs/superpowers/, .ai/thoughts/, and .ai/handoffs/. Before writing a new plan, check if one already exists.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { readOnlyHint: true, openWorldHint: false },
     },
     {
         name: 'read_document',
-        description: 'CALL AFTER list_documents when a file title looks relevant to the current task. Returns the full markdown content. Scoped to docs/plans/, docs/superpowers/, .ai/thoughts/ — reject anything else.',
+        description: 'CALL AFTER list_documents when a file title looks relevant to the current task. Returns the full markdown content. Scoped to docs/plans/, docs/superpowers/, .ai/thoughts/, .ai/handoffs/ — reject anything else.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -609,9 +621,13 @@ const GLOBAL_TOOLS = [
  * one of the ~35 workspace-scoped branches.
  */
 const GLOBAL_TOOL_NAMES = new Set(GLOBAL_TOOLS.map((t) => t.name));
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: workspaceId ? [...WORKSPACE_SCOPED_TOOLS, ...GLOBAL_TOOLS] : GLOBAL_TOOLS,
-}));
+function availableTools() {
+    const tools = workspaceId ? [...WORKSPACE_SCOPED_TOOLS, ...GLOBAL_TOOLS] : GLOBAL_TOOLS;
+    return tools.filter((tool) => handoffId && handoffToken
+        ? tool.name === 'submit_session_handoff' || tool.annotations?.readOnlyHint === true
+        : tool.name !== 'submit_session_handoff');
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: availableTools() }));
 /** Wrap a successful result as an MCP tool response with JSON text content. */
 function ok(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
@@ -641,6 +657,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return fail(`Tool '${name}' requires a workspace-bound MCP session (KOBO_WORKSPACE_ID not set).`);
     }
     try {
+        if (handoffId && handoffToken && !availableTools().some((tool) => tool.name === name))
+            return fail('This turn is reserved for a handoff report. Only read tools and submit_session_handoff are available.');
+        if (name === 'submit_session_handoff') {
+            if (!workspaceId || !handoffId || !handoffToken)
+                return fail('No handoff generation is active for this MCP invocation.');
+            return ok(await backendRequest('POST', `/api/workspaces/${workspaceId}/session-handoffs/${handoffId}/report`, {
+                token: handoffToken,
+                report: a.report,
+            }));
+        }
         if (WORKSPACE_DIALOGUE_TOOLS.some((tool) => tool.name === name)) {
             if (workspaceId && a.workspace_id === workspaceId && name === 'send_workspace_message')
                 return fail('Use the normal conversation to communicate in your own workspace.');

package/dist/server/db/migrations.js

@@ -3,6 +3,7 @@ import { initMcpMessageSchema } from './mcp-message-schema.js';
 import { initReviewReturnSchema } from './review-return-schema.js';
 import { initSchema } from './schema.js';
 import { initSearchSchema } from './search-schema.js';
+import { initSessionHandoffSchema } from './session-handoff-schema.js';
 /** Ordered registry of all schema migrations. Append new entries at the end. */
 export const migrations = [
     {
@@ -748,6 +749,19 @@ export const migrations = [
     { version: 43, name: 'durable-mcp-message-requests', migrate: initMcpMessageSchema },
     { version: 44, name: 'review-session-returns', migrate: initReviewReturnSchema },
     { version: 45, name: 'durable-auto-loop', migrate: initAutoLoopSchema },
+    { version: 46, name: 'session-handoffs', migrate: initSessionHandoffSchema },
+    {
+        version: 47,
+        name: 'session-activation-order',
+        migrate(db) {
+            const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'agent_sessions'").get();
+            if (!table)
+                return;
+            const columns = db.prepare('PRAGMA table_info(agent_sessions)').all();
+            if (!columns.some((column) => column.name === 'activation_order'))
+                db.exec('ALTER TABLE agent_sessions ADD COLUMN activation_order INTEGER NOT NULL DEFAULT 0');
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -2,6 +2,7 @@ import { initAutoLoopSchema } from './auto-loop-schema.js';
 import { initMcpMessageSchema } from './mcp-message-schema.js';
 import { initReviewReturnSchema } from './review-return-schema.js';
 import { initSearchSchema } from './search-schema.js';
+import { initSessionHandoffSchema } from './session-handoff-schema.js';
 /** Create all tables and indexes for a fresh install. Not used for upgrades -- see migrations.ts. */
 export function initSchema(db) {
     db.exec(`
@@ -70,7 +71,8 @@ export function initSchema(db) {
       ended_at TEXT,
       name TEXT,
       task_progress_baseline TEXT,
-      end_reason TEXT
+      end_reason TEXT,
+      activation_order INTEGER NOT NULL DEFAULT 0
     );
 
     CREATE TABLE IF NOT EXISTS ws_events (
@@ -229,4 +231,5 @@ export function initSchema(db) {
     initMcpMessageSchema(db);
     initReviewReturnSchema(db);
     initAutoLoopSchema(db);
+    initSessionHandoffSchema(db);
 }

package/dist/server/db/session-handoff-schema.js

@@ -0,0 +1,24 @@
+export function initSessionHandoffSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS session_handoffs (
+    id TEXT PRIMARY KEY,
+    workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+    request_id TEXT NOT NULL,
+    request_fingerprint TEXT NOT NULL,
+    source_session_id TEXT,
+    target_session_id TEXT,
+    source_configuration TEXT NOT NULL,
+    target_configuration TEXT NOT NULL,
+    source_model TEXT,
+    generate_summary INTEGER NOT NULL,
+    state TEXT NOT NULL,
+    report TEXT,
+    report_path TEXT,
+    generation_token TEXT,
+    error TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    UNIQUE(workspace_id, request_id)
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS session_handoffs_pending
+    ON session_handoffs(workspace_id) WHERE state NOT IN ('completed', 'cancelled');`);
+}

package/dist/server/index.js

@@ -43,6 +43,7 @@ import { startPrWatcher, stopPrWatcher } from './services/pr-watcher-service.js'
 import * as quotaBackoffService from './services/quota-backoff-service.js';
 import { reconcileReviewReturns } from './services/review-return-service.js';
 import { startSearchIndex, stopSearchIndex } from './services/search-service.js';
+import { reconcileSessionHandoffs } from './services/session-handoff-service.js';
 import { getGlobalSettings, updateNetworkAccessSettings } from './services/settings-service.js';
 import { reloadDefaultTemplates } from './services/templates-service.js';
 import { createTerminal, destroyAllTerminals, getTerminal } from './services/terminal-service.js';
@@ -118,6 +119,7 @@ const dailyBackupScheduler = startDailyDbBackupScheduler(async () => {
 // Initialize process cleanup, agent watchdog, PR watcher, and wakeup rehydration
 reconcileOrphanSessions();
 reconcileReviewReturns();
+reconcileSessionHandoffs();
 // Deliver any new default prompt templates to existing installs (seed-once via the
 // seededDefaultSlugs watermark; never overwrites or re-adds deleted defaults).
 try {

package/dist/server/routes/documents.js

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { Hono } from 'hono';
+import { DOCUMENT_DIRS } from '../../shared/document-roots.js';
 import * as workspaceService from '../services/workspace-service.js';
 import { isPathInside, resolveExistingPathInside } from '../utils/safe-path.js';
 /** Hono sub-router for workspace document browsing (read-only). */
@@ -13,7 +14,6 @@ const app = new Hono();
  * Kept intentionally narrow to avoid leaking unrelated project docs
  * (README, product specs, …) into the panel.
  */
-const DOCUMENT_DIRS = ['docs/plans', 'docs/superpowers', '.ai/thoughts'];
 /** Only .md files are listed. */
 const MD_EXT = '.md';
 /** Depth cap to keep recursion bounded even on pathological symlink loops. */

package/dist/server/routes/workspaces.js

@@ -1,8 +1,11 @@
 import { execFile as execFileCb, execFileSync, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
+import { nanoid } from 'nanoid';
 import { getSearchIndexStatus, searchEvents } from '../services/search-service.js';
+import { createSessionHandoff, decideSessionHandoff, getCurrentSessionHandoff, SessionHandoffError, submitSessionHandoff, waitForSessionHandoff, } from '../services/session-handoff-service.js';
 import { AgentStopError, assertAgentStopped } from '../utils/agent-stop-result.js';
 import { withGitRepoLock } from '../utils/git-repo-lock.js';
+import { workspaceLifecycleReason } from '../utils/workspace-lifecycle-guard.js';
 import autoLoopMessagesRoutes from './auto-loop-messages.js';
 const execFileAsync = promisify(execFileCb);
 import fs from 'node:fs';
@@ -64,6 +67,28 @@ function workspaceErrorStatus(err) {
 }
 /** Hono sub-router for workspace CRUD, tasks, agents, Git and PR creation. */
 const app = new Hono();
+// Transfers reserve the writer across multiple HTTP requests and engine invocations.
+app.use('/:id/*', async (c, next) => {
+    const id = c.req.param('id');
+    const route = c.req.path.split(`/api/workspaces/${id}/`)[1] ?? '';
+    if (!['GET', 'HEAD', 'OPTIONS'].includes(c.req.method) &&
+        workspaceLifecycleReason(id) === 'session-handoff' &&
+        !route.startsWith('session-handoffs') &&
+        ![
+            'stop',
+            'mark-read',
+            'chat-history',
+            'deferred-tool-use/answer',
+            'deferred-tool-use/cancel',
+            'deferred-permission/decision',
+        ].includes(route)) {
+        return c.json({
+            error: 'A session transfer is pending. Finish or cancel it before changing this workspace.',
+            code: 'workspace-busy',
+        }, 409);
+    }
+    await next();
+});
 // These handlers own teardown across awaits; purge/delete/restore own their guard in the service.
 for (const route of ['/:id/archive', '/:id/run-setup-script', '/:id/cancel-source-change', '/:id/rollback-file']) {
     app.use(route, async (c, next) => {
@@ -297,6 +322,44 @@ app.get('/', (c) => {
         return c.json({ error: message }, workspaceErrorStatus(err));
     }
 });
+function handoffError(c, error) {
+    return c.json({ error: error instanceof Error ? error.message : 'Session transfer failed' }, error instanceof SessionHandoffError
+        ? error.status
+        : error instanceof SyntaxError
+            ? 400
+            : workspaceErrorStatus(error));
+}
+app.post('/:id/session-handoffs', migrationGuard, async (c) => {
+    try {
+        return c.json({ handoff: createSessionHandoff(c.req.param('id'), await c.req.json()) }, 202);
+    }
+    catch (error) {
+        return handoffError(c, error);
+    }
+});
+app.get('/:id/session-handoffs/current', (c) => {
+    if (!workspaceService.getWorkspace(c.req.param('id')))
+        return c.json({ error: 'Workspace not found' }, 404);
+    return c.json({ handoff: getCurrentSessionHandoff(c.req.param('id')) });
+});
+app.post('/:id/session-handoffs/:handoffId/decision', migrationGuard, async (c) => {
+    try {
+        const body = await c.req.json();
+        return c.json({ handoff: await decideSessionHandoff(c.req.param('id'), c.req.param('handoffId'), body.action) });
+    }
+    catch (error) {
+        return handoffError(c, error);
+    }
+});
+app.post('/:id/session-handoffs/:handoffId/report', migrationGuard, async (c) => {
+    try {
+        const body = await c.req.json();
+        return c.json(submitSessionHandoff(c.req.param('id'), c.req.param('handoffId'), body.token, body.report));
+    }
+    catch (error) {
+        return handoffError(c, error);
+    }
+});
 // POST /api/workspaces/:id/engine-handoff-preview — build an editable, deterministic handoff.
 app.post('/:id/engine-handoff-preview', migrationGuard, async (c) => {
     try {
@@ -348,15 +411,14 @@ app.post('/:id/switch-engine', migrationGuard, async (c) => {
                 error: 'Workspace is compacting its context; wait until compaction finishes before sending a message',
             }, 409);
         }
-        // A new engine is started three lines below: the previous one must be dead
-        // first, or two agents share the worktree.
-        if (agentManager.hasController(id))
-            assertAgentStopped(await agentManager.stopAgentAndWait(id, undefined, 'replacement'));
-        const updated = workspaceService.updateWorkspaceEngineConfiguration(id, body.engine, model, effort, body.agentPermissionMode);
-        const session = agentManager.startAgent(id, updated.worktreePath, handoff, updated.model, false, updated.agentPermissionMode, undefined, updated.reasoningEffort);
-        workspaceService.updateWorkspaceStatus(id, 'executing');
-        wsService.emit(id, 'user:message', { content: handoff, sender: 'user', kind: 'engine-handoff' }, session.agentSessionId);
-        return c.json({ workspace: workspaceService.getWorkspace(id), sessionId: session.agentSessionId });
+        const operation = createSessionHandoff(id, {
+            requestId: nanoid(),
+            sourceSessionId: workspaceService.getActiveSession(id)?.id ?? null,
+            generateSummary: false,
+            target: { engine: body.engine, model, reasoningEffort: effort, agentPermissionMode: body.agentPermissionMode },
+        }, handoff);
+        const completed = await waitForSessionHandoff(operation.id);
+        return c.json({ workspace: workspaceService.getWorkspace(id), sessionId: completed.targetSessionId });
     }
     catch (err) {
         return c.json({ error: err instanceof Error ? err.message : 'Failed to switch engine' }, 500);
@@ -2629,6 +2691,8 @@ app.put('/:id/tags', async (c) => {
 });
 // PATCH /api/workspaces/:id — update workspace fields (status, model, agentPermissionMode, name)
 app.patch('/:id', migrationGuard, async (c) => {
+    if (workspaceLifecycleReason(c.req.param('id')) === 'session-handoff')
+        return c.json({ error: 'A session transfer is pending', code: 'workspace-busy' }, 409);
     try {
         const id = c.req.param('id');
         const parsed = await c.req.json();

package/dist/server/services/agent/engines/claude-code/engine.js

@@ -240,11 +240,25 @@ export function createClaudeCodeEngine() {
                 sdkOptions.pathToClaudeCodeExecutable = explicitBinary;
             const inputStream = new ClaudeInputStream(effectivePrompt);
             const q = query({ prompt: inputStream, options: sdkOptions });
+            let resolveReady;
+            let rejectReady;
+            const ready = new Promise((resolve, reject) => {
+                resolveReady = resolve;
+                rejectReady = reject;
+            });
+            // Legacy callers do not await readiness; still observe an early rejection.
+            void ready.catch(() => { });
             let discoveredSessionId;
             // A throwing onEvent handler (e.g. DB query against a closed connection
             // during async test teardown) must not escape as an unhandled rejection.
             const emitDirect = (ev) => {
                 try {
+                    if (ev.kind === 'session:started')
+                        resolveReady();
+                    if (ev.kind === 'error')
+                        rejectReady(new Error(ev.message));
+                    if (ev.kind === 'session:ended')
+                        rejectReady(new Error('Claude ended before confirming session initialization'));
                     onEvent(ev);
                 }
                 catch (err) {
@@ -588,6 +602,7 @@ export function createClaudeCodeEngine() {
                 }
             })();
             const engineProcess = {
+                ready,
                 closed: iteratorPromise.then(() => { }),
                 get pid() {
                     return undefined;

package/dist/server/services/agent/engines/codex/engine.js

@@ -574,6 +574,7 @@ export function createCodexEngine() {
                 }
             })();
             const engineProcess = {
+                ready: readyPromise,
                 closed: Promise.all([iteratorPromise, childExitedPromise]).then(() => { }),
                 get pid() {
                     return child.pid;