@loicngr/kobo 1.11.44 → 2.1.0

package/dist/server/routes/workspaces.js

@@ -1,8 +1,12 @@
 import { execFile as execFileCb, execFileSync, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
+import { nanoid } from 'nanoid';
+import { isWorkflowPolicy, resolveWorkflowPolicy, WORKFLOW_ACTIONS, } from '../../shared/workflow-policy.js';
 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 { isWorkspaceLifecycleBusy, workspaceLifecycleReason } from '../utils/workspace-lifecycle-guard.js';
 import autoLoopMessagesRoutes from './auto-loop-messages.js';
 const execFileAsync = promisify(execFileCb);
 import fs from 'node:fs';
@@ -59,11 +63,42 @@ import { WorkspaceLifecycleBusyError, withWorkspaceLifecycleGuard } from '../uti
 import { resolveExtractedName } from '../utils/workspace-name.js';
 import { resolveSiblingWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 /** Lifecycle conflicts can be retried once the current owner has stopped. */
+/** Symlink-resolved path, or the lexically resolved one when it does not exist. */
+function realPathOrResolved(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
 function workspaceErrorStatus(err) {
     return err instanceof AgentStopError || err instanceof WorkspaceLifecycleBusyError ? 409 : 500;
 }
 /** 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 +332,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 +421,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);
@@ -390,6 +462,8 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
     let setupScriptConfigured = false;
     try {
         const { body, attachments } = await readWorkspaceCreationRequest(c.req.raw);
+        if (body.workflowPolicy !== undefined && !isWorkflowPolicy(body.workflowPolicy))
+            return c.json({ error: 'Invalid workflowPolicy' }, 400);
         // workingBranch is derived from git when worktreePath is provided, so
         // it's not required in that flow. The other 3 fields stay mandatory.
         if (!body.name || !body.projectPath || !body.sourceBranch) {
@@ -490,11 +564,10 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                 return c.json({ error: failure, step: 'inspect-worktree' }, 422);
             }
             try {
-                const commonDir = execFileSync('git', ['-C', body.worktreePath, 'rev-parse', '--git-common-dir'], {
-                    encoding: 'utf-8',
-                }).trim();
-                const expectedCommonDir = path.join(body.projectPath, '.git');
-                if (path.resolve(commonDir) !== path.resolve(expectedCommonDir)) {
+                const commonDir = execFileSync('git', ['-C', body.worktreePath, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf-8' }).trim();
+                // Git reports the common dir symlink-resolved while the project path may be
+                // reached through a link (macOS temp dirs: /var -> /private/var).
+                if (realPathOrResolved(commonDir) !== realPathOrResolved(path.join(body.projectPath, '.git'))) {
                     const failure = `Worktree '${body.worktreePath}' belongs to a different repository`;
                     emitCreateFailed(creationId, 'inspect-worktree', failure);
                     return c.json({ error: failure, step: 'inspect-worktree' }, 422);
@@ -732,6 +805,7 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                 model: body.model,
                 brainstormModel: body.brainstormModel,
                 reasoningEffort: body.reasoningEffort,
+                workflowPolicy: resolveWorkflowPolicy(globalSettings.workflowPolicy, projectSettings?.workflowPolicy, body.workflowPolicy),
                 agentPermissionMode: resolveCreateAgentPermissionMode(body.agentPermissionMode, body.projectPath, globalSettings, body.engine ?? 'claude-code'),
                 engine: body.engine,
                 // Set by the engine-comparison flow, which posts here once per engine
@@ -1047,9 +1121,9 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                     `## Additional Context\n${extra}\n\n` +
                     `## MCP Tools for deeper analysis\n` +
                     `If you need more context, the following Sentry MCP tools are available:\n` +
-                    `- \`mcp__sentry__get_sentry_resource(url, resourceType)\` — fetch the issue, breadcrumbs, replay, or trace\n` +
-                    `- \`mcp__sentry__search_issue_events(organizationSlug, issueId='${sentryContent.issueId}')\` — recent events for this issue\n` +
-                    `- \`mcp__sentry__get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key)\` — filter by tag (environment, user, browser, …)\n`;
+                    `- \`get_sentry_resource(url, resourceType) [use the Kōbō-managed Sentry namespace supplied for this session]\` — fetch the issue, breadcrumbs, replay, or trace\n` +
+                    `- \`search_issue_events(organizationSlug, issueId='${sentryContent.issueId}')\` — recent events for this issue\n` +
+                    `- \`get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key)\` — filter by tag (environment, user, browser, …)\n`;
                 fs.writeFileSync(sentryFilePath, md, 'utf-8');
                 workspaceService.createTask(workspace.id, {
                     title: `Fix: ${sentryContent.title || sentryContent.issueId || `Sentry #${sentryContent.issueNumericId}`}`,
@@ -1170,9 +1244,9 @@ app.post('/', migrationGuard, creationBodyLimit, async (c) => {
                         `5. Confirm the test passes, run related tests\n` +
                         `6. Commit referencing the Sentry Short-ID (e.g. "fix(scope): description (${sentryContent.issueId})") — Sentry auto-closes the issue when the commit is merged\n` +
                         `\nIf you need more context, Sentry MCP tools are available:\n` +
-                        `- mcp__sentry__get_sentry_resource(url, resourceType) — fetch the issue, breadcrumbs, replay or trace\n` +
-                        `- mcp__sentry__search_issue_events(organizationSlug, issueId='${sentryContent.issueId}') — recent events\n` +
-                        `- mcp__sentry__get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key) — filter by tag\n`;
+                        `- get_sentry_resource(url, resourceType) [use the Kōbō-managed Sentry namespace supplied for this session] — fetch the issue, breadcrumbs, replay or trace\n` +
+                        `- search_issue_events(organizationSlug, issueId='${sentryContent.issueId}') — recent events\n` +
+                        `- get_issue_tag_values(organizationSlug, issueId='${sentryContent.issueId}', key) — filter by tag\n`;
                 if (sentryTpl.trim().length > 0) {
                     const renderedSentry = renderSentryInitialPrompt(sentryTpl, {
                         issueId: sentryContent.issueId,
@@ -1618,6 +1692,13 @@ app.get('/auto-loop-states', (c) => {
 });
 app.route('/', autoLoopMessagesRoutes);
 // GET /api/workspaces/:id/auto-loop — current auto-loop status for one workspace.
+// Admission inspection never changes deadlines, pending schedules or lifecycle state.
+app.get('/:id/automatic-admission', (c) => {
+    const id = c.req.param('id');
+    if (!workspaceService.getWorkspace(id))
+        return c.json({ error: 'Workspace not found' }, 404);
+    return c.json(autoLoopService.getAutomaticAdmissionStatus(id));
+});
 app.get('/:id/auto-loop', (c) => {
     try {
         const id = c.req.param('id');
@@ -2629,6 +2710,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();
@@ -2644,6 +2727,20 @@ app.patch('/:id', migrationGuard, async (c) => {
         if ('agent_description' in body) {
             return c.json({ error: 'agent_description must be set via the agent MCP tool, not via the API' }, 400);
         }
+        if (body.workflowPolicy !== undefined && !isWorkflowPolicy(body.workflowPolicy))
+            return c.json({ error: 'Invalid workflowPolicy' }, 400);
+        if (body.workflowPolicy !== undefined) {
+            const policy = resolveWorkflowPolicy(workspace.workflowPolicy, body.workflowPolicy);
+            const changed = WORKFLOW_ACTIONS.some((action) => policy[action] !== workspace.workflowPolicy[action]);
+            // A live engine already received its policy. Persisting a different one cannot
+            // revoke that prompt; wait for confirmed closure before accepting the change.
+            if (changed && (agentManager.hasController(id) || isWorkspaceLifecycleBusy(id))) {
+                return c.json({
+                    error: 'Stop the agent and wait for workspace operations to finish before changing workflow preferences.',
+                    code: 'workspace-busy',
+                }, 409);
+            }
+        }
         if (body.model !== undefined && (typeof body.model !== 'string' || !body.model.trim())) {
             return c.json({ error: 'model must be a non-empty string' }, 400);
         }
@@ -2685,6 +2782,7 @@ app.patch('/:id', migrationGuard, async (c) => {
             }
         }
         if (body.status === undefined &&
+            body.workflowPolicy === undefined &&
             body.model === undefined &&
             body.reasoningEffort === undefined &&
             body.agentPermissionMode === undefined &&

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;

package/dist/server/services/agent/engines/codex/options-builder.js

@@ -54,6 +54,7 @@ export function buildCodexOptions(input) {
         const mcpServersConfig = {};
         for (const srv of input.mcpServers) {
             mcpServersConfig[srv.name] = {
+                enabled: true,
                 command: srv.command,
                 args: srv.args,
                 env: srv.env,

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

@@ -1,5 +1,6 @@
 import { spawn as nodeSpawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 const requireFn = createRequire(import.meta.url);
 export function resolveCodexBinary() {
     try {
@@ -7,8 +8,7 @@ export function resolveCodexBinary() {
         const pkg = requireFn(pkgPath);
         const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.codex;
         if (binRel) {
-            const url = new URL(binRel, `file://${pkgPath}`);
-            return url.pathname;
+            return path.resolve(path.dirname(pkgPath), binRel);
         }
     }
     catch {

package/dist/server/services/agent/integration-mcp.js

@@ -0,0 +1,49 @@
+import { nanoid } from 'nanoid';
+import { readClaudeMcpEntry } from '../../utils/mcp-client.js';
+import { getIntegrationConfig } from '../integration-config-service.js';
+import { buildNotionMcpConfig } from '../notion-service.js';
+import { readSentryMcpConfig } from '../sentry-service.js';
+/** Availability only: no provider process or credential-bearing response. */
+export function hasIntegrationMcpConfig(integration, selectedKey) {
+    if (getIntegrationConfig(integration))
+        return true;
+    if (integration === 'notion' &&
+        (process.env.NOTION_API_TOKEN || process.env.NOTION_TOKEN || process.env.OPENAPI_MCP_HEADERS))
+        return true;
+    const key = selectedKey?.trim();
+    return Boolean(readClaudeMcpEntry((name) => key ? name === key : integration === 'notion' ? name === 'notion' : /sentry/i.test(name)));
+}
+/** Resolve at every launch/resume; never write credentials into a project file. */
+export function buildIntegrationMcpServers(settings, onUnavailable) {
+    const servers = [];
+    // Fresh names avoid Codex recursively merging stale native config fields.
+    const launch = nanoid(12);
+    for (const integration of ['notion', 'sentry']) {
+        if (!settings[`${integration}Enabled`])
+            continue;
+        try {
+            const key = settings[`${integration}McpKey`];
+            if (!hasIntegrationMcpConfig(integration, key))
+                continue;
+            const config = integration === 'notion' ? buildNotionMcpConfig(key, false) : readSentryMcpConfig(key, false);
+            servers.push({ name: `kobo-${integration}-${launch}`, ...config });
+        }
+        catch {
+            // Optional connections cannot block ordinary missions. Never expose raw
+            // config/parse errors, which may contain credential material.
+            onUnavailable?.(integration);
+        }
+    }
+    return servers;
+}
+export function integrationMcpPrompt(servers, unavailable = []) {
+    if (!servers.length && !unavailable.length)
+        return '';
+    return [
+        '[Kōbō managed integrations]',
+        ...unavailable.map((name) => `${name}: Kōbō could not load this connection. Ask the user to check Settings if needed; do not silently substitute personal credentials.`),
+        'For these integrations, use the MCP servers listed below, configured in Kōbō Settings. Prefer them over personal/native servers and namespaces from earlier turns. Discover their available tools; do not assume all servers implement the same tools. If unavailable, report the connection problem instead of silently switching credentials.',
+        ...servers.map((server) => `${server.name.startsWith('kobo-notion-') ? 'Notion' : 'Sentry'}: ${server.name}`),
+        'These connections do not grant permission to modify remote data. Follow the user request and engine permissions.',
+    ].join('\n');
+}

package/dist/server/services/agent/orchestrator.js

@@ -1,9 +1,10 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { nanoid } from 'nanoid';
+import { renderWorkflowPolicy } from '../../../shared/workflow-policy.js';
 import { getDb } from '../../db/index.js';
 import { assertAgentStopped } from '../../utils/agent-stop-result.js';
 import { ensureKoboHome, getCompiledMcpServerPath, getDbPath, getKoboHome, getMcpServerSourcePath, getSettingsPath, getSkillsPath, } from '../../utils/paths.js';
-import { assertWorkspaceLifecycleAvailable } from '../../utils/workspace-lifecycle-guard.js';
+import { assertWorkspaceLifecycleAvailable, workspaceLifecycleReason } from '../../utils/workspace-lifecycle-guard.js';
 import { listLoopMessages, settleLoopMessages } from '../auto-loop-message-service.js';
 import * as autoLoopService from '../auto-loop-service.js';
 import * as cleanupScriptService from '../cleanup-script-service.js';
@@ -12,6 +13,8 @@ import { resolveForge } from '../forge/resolve.js';
 import * as lifecycleHookService from '../lifecycle-hook-service.js';
 import * as quotaBackoffService from '../quota-backoff-service.js';
 import { buildReviewReturnPrompt, getReviewReturn, restoreReviewConfiguration } from '../review-return-service.js';
+import { activateSession, SESSION_RECENCY_ORDER } from '../session-activity-service.js';
+import { requestHandoffStop, suspendHandoffTransfers } from '../session-handoff-runtime.js';
 import { getEffectiveSettings, getGlobalSettings } from '../settings-service.js';
 import { refreshNow } from '../usage/poller.js';
 import * as wakeupService from '../wakeup-service.js';
@@ -21,6 +24,7 @@ import { getWorkspace as getWs, markWorkspaceUnread, updateWorkspaceStatus, } fr
 import { resolveEngine } from './engines/registry.js';
 import { AGENT_NO_LONGER_RUNNING_TEXT, } from './engines/types.js';
 import { routeEvent } from './event-router.js';
+import { buildIntegrationMcpServers, integrationMcpPrompt } from './integration-mcp.js';
 import { SessionController } from './session-controller.js';
 export class InterruptAgentError extends Error {
     code;
@@ -474,7 +478,7 @@ function readEffectiveSettingsSafe(projectPath) {
         };
     }
 }
-function buildMcpServers(workspaceId) {
+function buildMcpServers(workspaceId, extraEnv) {
     const mcpServerCompiled = getCompiledMcpServerPath();
     const mcpServerSource = getMcpServerSourcePath();
     return [
@@ -484,6 +488,7 @@ function buildMcpServers(workspaceId) {
             args: mcpServerCompiled ? [mcpServerCompiled] : ['tsx', mcpServerSource],
             env: {
                 KOBO_WORKSPACE_ID: workspaceId,
+                ...extraEnv,
                 KOBO_DB_PATH: getDbPath(),
                 KOBO_SETTINGS_PATH: getSettingsPath(),
                 KOBO_BACKEND_URL: `http://127.0.0.1:${backendPort}`,
@@ -540,7 +545,7 @@ function resolveSessionForResume(workspaceId, existingSessionId, model, engineId
     }
     else {
         lastSession = db
-            .prepare("SELECT id, engine_session_id, engine FROM agent_sessions WHERE workspace_id = ? AND COALESCE(engine, 'claude-code') = ? AND engine_session_id IS NOT NULL ORDER BY started_at DESC LIMIT 1")
+            .prepare(`SELECT id, engine_session_id, engine FROM agent_sessions WHERE workspace_id = ? AND COALESCE(engine, 'claude-code') = ? AND engine_session_id IS NOT NULL AND activation_order >= 0 ORDER BY ${SESSION_RECENCY_ORDER} LIMIT 1`)
             .get(workspaceId, engineId);
     }
     // A workspace can now contain conversations from multiple engines. The
@@ -841,6 +846,13 @@ function handleEvent(workspaceId, agentSessionId, sourceController, ev, terminal
         return;
     const routedEvent = ev.kind === 'session:ended' && (hasReplacement || sourceIsSuperseded) ? { ...ev, superseded: true } : ev;
     routeEvent(workspaceId, agentSessionId, routedEvent);
+    const launch = sourceController ? launchOptions.get(sourceController) : undefined;
+    if (ev.kind === 'error')
+        launch?.onError?.(ev.message);
+    // Summary turns can read and report, but must not drive loop/quota/scheduler side effects.
+    if (launch?.handoffGeneration &&
+        !['session:started', 'session:ended', 'session:user-input-requested'].includes(ev.kind))
+        return;
     if (sourceController && !sourceControllerIsStopping) {
         if (ev.kind === 'session:compacting' && ev.active) {
             const status = getWs(workspaceId)?.status;
@@ -958,9 +970,10 @@ function handleEvent(workspaceId, agentSessionId, sourceController, ev, terminal
             console.error('[orchestrator] Failed to transition to executing:', err);
         }
     }
+    const transferring = workspaceLifecycleReason(workspaceId) === 'session-handoff';
     const returningReview = (ev.kind === 'error' || ev.kind === 'session:ended') && !!getReviewReturn(workspaceId, agentSessionId);
     const quotaError = ev.kind === 'error' && (ev.category === 'quota' || /\b429\b/.test(ev.message));
-    if (quotaError && !sourceControllerIsStopping && !returningReview) {
+    if (quotaError && !sourceControllerIsStopping && !returningReview && !transferring) {
         void handleQuota(workspaceId, agentSessionId);
     }
     if (ev.kind === 'error' &&
@@ -968,6 +981,7 @@ function handleEvent(workspaceId, agentSessionId, sourceController, ev, terminal
         ev.category !== 'resume_failed' &&
         TRANSIENT_SERVER_ERROR_PATTERN.test(ev.message) &&
         !returningReview &&
+        !transferring &&
         getWs(workspaceId)?.autoLoop &&
         !sourceControllerIsStopping) {
         scheduleTransientAutoLoopRecovery(workspaceId, sourceController);
@@ -989,6 +1003,22 @@ function handleEvent(workspaceId, agentSessionId, sourceController, ev, terminal
         // its persisted prompts too, otherwise a reconnect resurrects a panel
         // whose backend callback has already been discarded.
         purgeAllPersistedUserInputRequests(workspaceId, agentSessionId);
+        if (transferring) {
+            onSessionEnded(workspaceId, agentSessionId, sourceController, ev.exitCode, ev.reason, isResumeFailed);
+            launch?.onEnded?.(ev);
+            if (workspaceLifecycleReason(workspaceId) === 'session-handoff') {
+                if (!launch?.handoffGeneration) {
+                    settleLoopMessages(workspaceId, agentSessionId, ev.reason === 'completed');
+                    if (listLoopMessages(workspaceId).some((message) => message.state === 'unknown'))
+                        autoLoopService.block(workspaceId, 'message-delivery-unknown');
+                }
+                notifyCapacityAvailable(workspaceId);
+                return;
+            }
+            // A target can finish before its ready/start promise settles. Its callback
+            // completed the transfer and released ownership: process this actual work
+            // session through the ordinary terminal/auto-loop path below exactly once.
+        }
         // A watchdog end means Kōbō forced the stream closed after the engine
         // failed to drain. It is neither a clean completion nor evidence of an
         // agent stall. Move auto-loop work onto the existing persisted, bounded
@@ -1190,6 +1220,11 @@ function onSessionEnded(workspaceId, agentSessionId, sourceController, exitCode,
         preCompactionStatus.delete(sourceController);
     if (isSuperseded)
         return false;
+    if (workspaceLifecycleReason(workspaceId) === 'session-handoff') {
+        if (registeredController === sourceController && sourceController?.status !== 'stopping')
+            controllers.delete(workspaceId);
+        return false;
+    }
     // A superseded end (above) is a session that was replaced, not one that
     // ended; everything past this point is a real end the user may want to act
     // on, whatever the reason — the script reads KOBO_SESSION_END_REASON.
@@ -1254,6 +1289,7 @@ function onSessionEnded(workspaceId, agentSessionId, sourceController, exitCode,
     }
     return true;
 }
+const launchOptions = new WeakMap();
 // ── Public API ────────────────────────────────────────────────────────────────
 /**
  * Spawn an agent (via the resolved engine) for a workspace. Returns
@@ -1261,10 +1297,10 @@ function onSessionEnded(workspaceId, agentSessionId, sourceController, exitCode,
  * after `engine.start` resolves — callers should subscribe to WS events or
  * query the controller via `_getControllers()` for tests.
  */
-export function startAgent(workspaceId, workingDir, prompt, model, resume = false, agentPermissionMode, existingSessionId, reasoningEffort, beforeDispatch) {
+export function startAgent(workspaceId, workingDir, prompt, model, resume = false, agentPermissionMode, existingSessionId, reasoningEffort, beforeDispatch, launch) {
     if (shuttingDown)
         throw new Error('Cannot start an agent while the server is shutting down');
-    assertWorkspaceLifecycleAvailable(workspaceId);
+    assertWorkspaceLifecycleAvailable(workspaceId, launch?.lifecycleOwner);
     const workspace = getWs(workspaceId);
     if (!workspace)
         throw new Error(`Workspace '${workspaceId}' not found`);
@@ -1334,12 +1370,15 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     }
     // Persist before the asynchronous engine can emit its first event. This
     // survives a Kōbō restart and does not depend on SDK system:init delivery.
+    activateSession(workspaceId, agentSessionId);
     captureTaskProgressBaseline(workspaceId, agentSessionId);
     const settings = ws ? readEffectiveSettingsSafe(ws.projectPath) : readEffectiveSettingsSafe(workingDir);
+    const unavailableIntegrations = [];
+    const integrationServers = buildIntegrationMcpServers(getGlobalSettings(), (name) => unavailableIntegrations.push(name));
     const options = {
         workspaceId,
         workingDir,
-        prompt: buildAgentPrompt(prompt, ws?.projectPath),
+        prompt: buildAgentPrompt(`${ws ? renderWorkflowPolicy(ws.workflowPolicy) : ''}\n${integrationMcpPrompt(integrationServers, unavailableIntegrations)}\n${prompt}`, ws?.projectPath),
         model,
         effort: reasoningEffort,
         // Cascade: explicit caller override → workspace setting → 'bypass'.
@@ -1355,12 +1394,14 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             }
         })(),
         settings,
-        mcpServers: buildMcpServers(workspaceId),
+        mcpServers: [...buildMcpServers(workspaceId, launch?.mcpEnv), ...integrationServers],
         env: ws ? buildAgentEnv(ws.projectPath) : undefined,
     };
     beforeDispatch?.();
     let controller;
     controller = new SessionController(workspaceId, agentSessionId, engine, (ev) => handleEvent(workspaceId, agentSessionId, controller, ev));
+    if (launch)
+        launchOptions.set(controller, launch);
     registerSessionLifecycleOwner(workspaceId, agentSessionId, controller);
     if (!existingCtrl)
         controllers.set(workspaceId, controller);
@@ -1377,7 +1418,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
             return;
         if (pendingStarts.get(workspaceId) === controller)
             pendingStarts.delete(workspaceId);
-        assertWorkspaceLifecycleAvailable(workspaceId);
+        assertWorkspaceLifecycleAvailable(workspaceId, launch?.lifecycleOwner);
         const current = getWs(workspaceId);
         if (!current || current.archivedAt || current.worktreePurgedAt)
             throw new Error('Workspace is no longer available');
@@ -1387,7 +1428,11 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
         controllers.set(workspaceId, controller);
         return controller.start(options);
     })
-        .then(() => {
+        .then(async () => {
+        if (launch?.onStarted)
+            await controller.engineProcess?.ready;
+        if (controller.status !== 'stopping')
+            launch?.onStarted?.();
         const pid = controller.pid;
         if (pid !== undefined) {
             try {
@@ -1524,6 +1569,9 @@ async function raceWithTimeout(promise, timeoutMs, onTimeout) {
 export async function stopAgentAndWait(workspaceId, timeoutMs = STOP_AGENT_TIMEOUT_MS, 
 /** Only `user` disables auto-loop; technical stops preserve its persisted intent. */
 cause = 'user') {
+    const finishHandoffStop = ['user', 'delete', 'purge', 'archive'].includes(cause)
+        ? requestHandoffStop(workspaceId)
+        : undefined;
     const pending = pendingStarts.get(workspaceId);
     let pendingStop = Promise.resolve();
     if (pending) {
@@ -1544,7 +1592,8 @@ cause = 'user') {
     // Shutdown only suspends timers: persisted intent belongs to the next boot.
     const cancelSchedules = new Promise((resolve) => {
         if (cause !== 'shutdown') {
-            wakeupService.cancel(workspaceId, 'stopped');
+            if (cause !== 'handoff')
+                wakeupService.cancel(workspaceId, 'stopped');
             quotaBackoffService.cancel(workspaceId, 'user');
         }
         resolve();
@@ -1561,6 +1610,7 @@ cause = 'user') {
     if (outcome === 'timeout') {
         console.error(`[orchestrator] Agent '${workspaceId}' did not stop within ${timeoutMs}ms; retaining its controller`);
     }
+    finishHandoffStop?.(outcome);
     return outcome;
 }
 /**
@@ -1584,6 +1634,7 @@ export async function stopAllAgents(timeoutMs = 3_000) {
     wakeupService.suspendForShutdown();
     cronService.suspendForShutdown();
     shuttingDown = true;
+    suspendHandoffTransfers();
     if (capacityTimer)
         clearTimeout(capacityTimer);
     capacityTimer = undefined;
@@ -1603,6 +1654,8 @@ export function isShuttingDown() {
 }
 /** Deliver a scheduled check without stopping background work or cancelling the wakeup as user input. */
 export function sendWakeupIfWaiting(workspaceId, content, expectedSessionId) {
+    if (workspaceLifecycleReason(workspaceId) === 'session-handoff')
+        return false;
     const ctrl = controllers.get(workspaceId);
     if (ctrl?.status !== 'running')
         return false;
@@ -1620,6 +1673,7 @@ export function sendWakeupIfWaiting(workspaceId, content, expectedSessionId) {
 }
 /** Write a user message to the running agent. */
 export async function sendMessage(workspaceId, content, expectedSessionId, beforeDispatch) {
+    assertWorkspaceLifecycleAvailable(workspaceId);
     assertWorkspaceNotCompacting(workspaceId);
     const ctrl = controllers.get(workspaceId);
     if (!ctrl) {
@@ -1633,6 +1687,7 @@ export async function sendMessage(workspaceId, content, expectedSessionId, befor
     await ctrl.sendMessage(content);
 }
 export async function sendMessageForFallback(workspaceId, content) {
+    assertWorkspaceLifecycleAvailable(workspaceId);
     assertWorkspaceNotCompacting(workspaceId);
     const capturedController = controllers.get(workspaceId);
     wakeupService.cancel(workspaceId, 'user-message');
@@ -1643,6 +1698,7 @@ export async function sendMessageForFallback(workspaceId, content) {
         return { status: 'sent', sessionId: capturedController.agentSessionId };
     }
     catch {
+        assertWorkspaceLifecycleAvailable(workspaceId);
         assertWorkspaceNotCompacting(workspaceId);
         const deadline = Date.now() + FALLBACK_CONTROLLER_TURNOVER_TIMEOUT_MS;
         while (controllers.get(workspaceId) === capturedController) {
@@ -1657,6 +1713,7 @@ export async function sendMessageForFallback(workspaceId, content) {
         const replacementController = controllers.get(workspaceId);
         if (!replacementController)
             return { status: 'stopped' };
+        assertWorkspaceLifecycleAvailable(workspaceId);
         assertWorkspaceNotCompacting(workspaceId);
         await replacementController.sendMessage(content);
         return { status: 'sent', sessionId: replacementController.agentSessionId };