@loicngr/kobo 2.1.2 → 2.1.5

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

@@ -124,9 +124,52 @@ export function createClaudeCodeEngine() {
         async start(options, onEvent) {
             const abortController = new AbortController();
             const mapperState = createMapperState();
-            // UI/tool ids can differ from the SDK task id. Key by the stable UI id
-            // so a terminal notification that omits task_id still clears the task.
-            const activeSubagentTaskIds = new Map();
+            // Active sub-agents keyed by their canonical id (SDK task id when known,
+            // else the tool call id), which is also the id passed to `q.stopTask`.
+            // One task can surface under both ids (relaunch, kill/restart), so
+            // running and terminal events must resolve to the same entry.
+            const activeSubagentTaskIds = new Set();
+            // tool call id -> SDK task id, learned from events carrying both.
+            const subagentTaskIdByToolCallId = new Map();
+            // Ambient tasks (SDK `ambient`, e.g. Monitor watchers) are not activity:
+            // they never enter `activeSubagentTaskIds`, so they never block
+            // turn:completed, keep the input open or arm the stall watchdog. They are
+            // tracked apart only so a user interrupt still stops them.
+            const ambientSubagentTaskIds = new Set();
+            // Canonical ids whose last lifecycle event was terminal: a late
+            // `progress` for them is ignored, only a `started` relaunch revives them.
+            const terminalSubagentTaskIds = new Set();
+            const trackSubagentProgress = (ev) => {
+                if (ev.taskId) {
+                    subagentTaskIdByToolCallId.set(ev.toolCallId, ev.taskId);
+                    // Merge an entry first tracked under its tool call id alone.
+                    if (ev.toolCallId !== ev.taskId) {
+                        activeSubagentTaskIds.delete(ev.toolCallId);
+                        ambientSubagentTaskIds.delete(ev.toolCallId);
+                        if (terminalSubagentTaskIds.delete(ev.toolCallId))
+                            terminalSubagentTaskIds.add(ev.taskId);
+                    }
+                }
+                const taskId = ev.taskId ?? subagentTaskIdByToolCallId.get(ev.toolCallId);
+                const key = taskId ?? ev.toolCallId;
+                if (ev.status !== 'running') {
+                    activeSubagentTaskIds.delete(key);
+                    ambientSubagentTaskIds.delete(key);
+                    terminalSubagentTaskIds.add(key);
+                    return;
+                }
+                if (ev.phase === 'progress' && terminalSubagentTaskIds.has(key))
+                    return;
+                terminalSubagentTaskIds.delete(key);
+                if (ev.ambient) {
+                    activeSubagentTaskIds.delete(key);
+                    ambientSubagentTaskIds.add(key);
+                }
+                else {
+                    ambientSubagentTaskIds.delete(key);
+                    activeSubagentTaskIds.add(key);
+                }
+            };
             // Foreground tool calls currently awaiting their tool_result. Cleared on
             // every `result` message: a turn cannot end with a tool still in flight.
             const pendingToolCallIds = new Set();
@@ -260,6 +303,17 @@ export function createClaudeCodeEngine() {
                 sdkOptions.pathToClaudeCodeExecutable = explicitBinary;
             const inputStream = new ClaudeInputStream(effectivePrompt);
             const q = query({ prompt: inputStream, options: sdkOptions });
+            // Best-effort SDK stop of one background task; failures are ignored.
+            const requestStopTask = (taskId) => {
+                try {
+                    void q.stopTask(taskId).catch(() => {
+                        /* best-effort */
+                    });
+                }
+                catch {
+                    /* best-effort */
+                }
+            };
             let resolveReady;
             let rejectReady;
             const ready = new Promise((resolve, reject) => {
@@ -507,15 +561,14 @@ export function createClaudeCodeEngine() {
                         clearResultDrainWatchdog();
                         const events = mapSdkMessage(msg, mapperState);
                         for (const ev of events) {
-                            if (ev.kind !== 'subagent:progress')
-                                continue;
-                            if (ev.status === 'running')
-                                activeSubagentTaskIds.set(ev.toolCallId, ev.taskId ?? ev.toolCallId);
-                            else
-                                activeSubagentTaskIds.delete(ev.toolCallId);
+                            if (ev.kind === 'subagent:progress')
+                                trackSubagentProgress(ev);
                         }
                         if (activeSubagentTaskIds.size > 0 &&
-                            (events.some((ev) => ev.kind === 'subagent:progress' ||
+                            (events.some((ev) => 
+                            // An ambient watcher's progress is not proof that a real
+                            // sub-agent advanced: it must not reset the stall bound.
+                            (ev.kind === 'subagent:progress' && !ev.ambient) ||
                                 ev.kind === 'message:text' ||
                                 ev.kind === 'message:thinking' ||
                                 ev.kind === 'tool:call' ||
@@ -689,6 +742,28 @@ export function createClaudeCodeEngine() {
                     armSubagentStallWatchdog();
                     return true;
                 },
+                stopSubagents(ids) {
+                    const isRunning = (taskId) => activeSubagentTaskIds.has(taskId) || ambientSubagentTaskIds.has(taskId);
+                    const targets = new Set();
+                    if (ids === undefined) {
+                        for (const taskId of [...activeSubagentTaskIds, ...ambientSubagentTaskIds])
+                            targets.add(taskId);
+                    }
+                    else {
+                        for (const id of ids) {
+                            // A card id is the SDK task id, or the tool call id when the
+                            // task id was not known yet: resolve both to the tracked entry.
+                            const taskId = isRunning(id) ? id : subagentTaskIdByToolCallId.get(id);
+                            if (taskId && isRunning(taskId))
+                                targets.add(taskId);
+                        }
+                    }
+                    // The main turn keeps running: only the targeted tasks are stopped.
+                    // Their terminal notification clears the tracking as usual.
+                    for (const taskId of targets)
+                        requestStopTask(taskId);
+                    return targets.size;
+                },
                 interrupt() {
                     userInterrupted = true;
                     // The SDK ends an interrupted run by emitting a `result` with
@@ -699,16 +774,8 @@ export function createClaudeCodeEngine() {
                     // background subagent task keeps running unless told to stop via
                     // its own API, which would otherwise leave the Stop button
                     // appearing to do nothing for up to SUBAGENT_STALL_TIMEOUT_MS.
-                    for (const taskId of activeSubagentTaskIds.values()) {
-                        try {
-                            void q.stopTask(taskId).catch(() => {
-                                /* best-effort */
-                            });
-                        }
-                        catch {
-                            /* best-effort */
-                        }
-                    }
+                    for (const taskId of [...activeSubagentTaskIds, ...ambientSubagentTaskIds])
+                        requestStopTask(taskId);
                     const qq = q;
                     if (typeof qq.interrupt === 'function') {
                         try {

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

@@ -77,6 +77,21 @@ export const QUOTA_PATTERN = /\b429\b|out of extra usage|rate[_ ]limit|usage lim
  * of a previous attempt, a sub-agent failure, or application HTTP handling.
  */
 const ASSISTANT_QUOTA_NOTICE = /^(?:you(?:'|’)re out of extra usage|you(?:'|’)ve hit your (?:session|weekly|usage) limit|claude ai usage limit reached|usage limit reached|quota exceeded|rate limit exceeded)(?:[.!]?(?:[ \t]*[·—-]?[ \t]*resets?\b[^\r\n]*)?)?[.!]?$/i;
+/** SDKTaskNotificationMessage.status -> subagent:progress terminal status. */
+const TASK_NOTIFICATION_STATUS = {
+    completed: 'done',
+    failed: 'failed',
+    stopped: 'stopped',
+};
+/**
+ * SDKTaskUpdatedMessage.patch.status values that end a task. `pending`,
+ * `running` and `paused` are not lifecycle edges and are ignored.
+ */
+const TASK_UPDATED_TERMINAL_STATUS = {
+    completed: 'done',
+    failed: 'failed',
+    killed: 'stopped',
+};
 export function createMapperState() {
     return {
         sessionStartedEmitted: false,
@@ -84,6 +99,8 @@ export function createMapperState() {
         sawErrorResult: false,
         quotaErrorEmitted: false,
         userInterrupted: false,
+        taskToolUseIds: new Map(),
+        taskFlags: new Map(),
     };
 }
 /** Known SDK `result` subtypes that indicate the run failed. */
@@ -191,30 +208,79 @@ export function mapSdkMessage(msg, state) {
             events.push({ kind: 'session:compacting', active: sdkStatus === 'compacting' });
             return events;
         }
-        if (subtype === 'task_started' || subtype === 'task_progress' || subtype === 'task_notification') {
+        if (subtype === 'task_started' ||
+            subtype === 'task_progress' ||
+            subtype === 'task_notification' ||
+            subtype === 'task_updated') {
             const taskId = typeof parsed.task_id === 'string' ? parsed.task_id : undefined;
-            const toolCallId = typeof parsed.tool_use_id === 'string' ? parsed.tool_use_id : taskId;
-            if (toolCallId) {
-                const usage = parsed.usage;
-                // Unlike task_started/task_progress (in-flight signals), task_notification
-                // is only ever emitted once a task settles — its `status` value is a
-                // reason, not a liveness signal. Treat every task_notification as
-                // terminal instead of matching against a status whitelist, so an SDK
-                // status value added later doesn't leave the subagent stuck 'running'.
-                const isDone = subtype === 'task_notification';
-                events.push({
-                    kind: 'subagent:progress',
-                    toolCallId,
-                    ...(taskId ? { taskId } : {}),
-                    status: isDone ? 'done' : 'running',
-                    description: typeof parsed.description === 'string' ? parsed.description : undefined,
-                    taskType: typeof parsed.task_type === 'string' ? parsed.task_type : undefined,
-                    lastToolName: typeof parsed.last_tool_name === 'string' ? parsed.last_tool_name : undefined,
-                    totalTokens: typeof usage?.total_tokens === 'number' ? usage.total_tokens : undefined,
-                    toolUses: typeof usage?.tool_uses === 'number' ? usage.tool_uses : undefined,
-                    durationMs: typeof usage?.duration_ms === 'number' ? usage.duration_ms : undefined,
-                });
+            const toolUseId = typeof parsed.tool_use_id === 'string' ? parsed.tool_use_id : undefined;
+            if (taskId && toolUseId)
+                state.taskToolUseIds.set(taskId, toolUseId);
+            const toolCallId = toolUseId ?? (taskId ? (state.taskToolUseIds.get(taskId) ?? taskId) : undefined);
+            if (!toolCallId)
+                return events;
+            let status;
+            let phase;
+            if (subtype === 'task_updated') {
+                // Only a terminal patch status is a lifecycle signal; other patches
+                // (pending/running/paused, description, is_backgrounded...) are ignored.
+                const patch = parsed.patch;
+                const patchStatus = TASK_UPDATED_TERMINAL_STATUS[String(patch?.status)];
+                if (!patchStatus)
+                    return events;
+                status = patchStatus;
+            }
+            else if (subtype === 'task_notification') {
+                // task_notification is only ever emitted once a task settles: an
+                // unknown status value is still terminal (`done`), so a future SDK
+                // value never leaves the sub-agent stuck 'running'.
+                status = TASK_NOTIFICATION_STATUS[String(parsed.status)] ?? 'done';
+            }
+            else {
+                status = 'running';
+                phase = subtype === 'task_started' ? 'started' : 'progress';
+            }
+            if (taskId) {
+                const hasAmbient = typeof parsed.ambient === 'boolean';
+                const hasSkip = typeof parsed.skip_transcript === 'boolean';
+                if (subtype === 'task_started') {
+                    // A (re)launch defines the task's classification afresh.
+                    state.taskFlags.set(taskId, {
+                        ...(hasAmbient ? { ambient: parsed.ambient } : {}),
+                        ...(hasSkip ? { skipTranscript: parsed.skip_transcript } : {}),
+                    });
+                }
+                else if (hasAmbient || hasSkip) {
+                    state.taskFlags.set(taskId, {
+                        ...state.taskFlags.get(taskId),
+                        ...(hasAmbient ? { ambient: parsed.ambient } : {}),
+                        ...(hasSkip ? { skipTranscript: parsed.skip_transcript } : {}),
+                    });
+                }
             }
+            const flags = taskId ? state.taskFlags.get(taskId) : undefined;
+            const usage = parsed.usage;
+            const description = typeof parsed.description === 'string'
+                ? parsed.description
+                : subtype === 'task_updated' &&
+                    typeof parsed.patch?.description === 'string'
+                    ? parsed.patch.description
+                    : undefined;
+            events.push({
+                kind: 'subagent:progress',
+                toolCallId,
+                ...(taskId ? { taskId } : {}),
+                status,
+                ...(phase ? { phase } : {}),
+                ...(flags?.ambient ? { ambient: true } : {}),
+                ...(flags?.skipTranscript ? { skipTranscript: true } : {}),
+                description,
+                taskType: typeof parsed.task_type === 'string' ? parsed.task_type : undefined,
+                lastToolName: typeof parsed.last_tool_name === 'string' ? parsed.last_tool_name : undefined,
+                totalTokens: typeof usage?.total_tokens === 'number' ? usage.total_tokens : undefined,
+                toolUses: typeof usage?.tool_uses === 'number' ? usage.tool_uses : undefined,
+                durationMs: typeof usage?.duration_ms === 'number' ? usage.duration_ms : undefined,
+            });
             return events;
         }
         if (subtype === 'init') {

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

@@ -14,6 +14,7 @@ const KOBO_MCP_BRIEF = [
     '• `kobo__set_workspace_status` when the mission is done or irrecoverably blocked. Never set `idle` while this session is active; use AskUserQuestion for clarification, or end the turn.',
     '• `kobo__schedule_wakeup` / `kobo__cancel_wakeup` to schedule (or cancel) a follow-up session — prefer these over the built-in `ScheduleWakeup` tool.',
     'Each tool carries its own "WHEN to use" guidance in its description — follow it.',
+    'Only one agent edits the worktree at a time: do not run background subagents that modify files while you or another subagent modify files too. Parallel read-only subagents (search, analysis, review) are fine. Wait for a file-editing subagent to finish before editing or running tests yourself, and remember that changes appearing in the worktree may come from your own subagents.',
 ].join('\n');
 /**
  * Appended to the Claude Code preset system prompt so the rule is always in

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

@@ -340,13 +340,35 @@ export function createCodexEngine() {
                         if (n.item.type === 'fileChange')
                             fileChanges.set(itemKey(n.threadId, n.turnId, n.item.id), n.item);
                         const events = mapTurnEvents(n, (state) => handleItemCompleted(n.item, state));
+                        const collabItem = n.item.type === 'collabAgentToolCall' ? n.item : undefined;
+                        const isActiveAgent = (status) => status === 'pendingInit' || status === 'running';
+                        const progressIndex = events.findIndex((event) => event.kind === 'subagent:progress');
+                        if (collabItem && progressIndex >= 0) {
+                            // The card that first tracked a thread (normally its spawnAgent)
+                            // owns it until it finishes. A later wait/sendInput/resumeAgent
+                            // on an already-owned thread (e.g. a wait that timed out) must
+                            // not steal it, or the owner card is orphaned in `running`; such
+                            // a card is done as soon as its own call completes.
+                            const progress = events[progressIndex];
+                            const ownsActiveThread = Object.entries(collabItem.agentsStates).some(([threadId, agentState]) => {
+                                if (!isActiveAgent(agentState.status))
+                                    return false;
+                                const owner = activeSubagentThreads.get(threadId);
+                                return !owner || owner.toolCallId === progress.toolCallId;
+                            });
+                            if (progress.status === 'running' && !ownsActiveThread) {
+                                events[progressIndex] = { ...progress, status: 'done' };
+                            }
+                        }
                         for (const ev of events)
                             safeEmit(ev);
-                        if (n.item.type === 'collabAgentToolCall') {
-                            const progress = events.find((event) => event.kind === 'subagent:progress');
-                            for (const [threadId, agentState] of Object.entries(n.item.agentsStates)) {
-                                if (agentState.status === 'pendingInit' || agentState.status === 'running') {
-                                    if (progress) {
+                        if (collabItem) {
+                            const progress = progressIndex >= 0
+                                ? events[progressIndex]
+                                : undefined;
+                            for (const [threadId, agentState] of Object.entries(collabItem.agentsStates)) {
+                                if (isActiveAgent(agentState.status)) {
+                                    if (progress && !activeSubagentThreads.has(threadId)) {
                                         activeSubagentThreads.set(threadId, {
                                             toolCallId: progress.toolCallId,
                                             description: progress.description,

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

@@ -11,6 +11,7 @@ const CODEX_KOBO_MCP_BRIEF = [
     '• `mcp__kobo-tasks__set_workspace_status` when the mission is done or irrecoverably blocked. Never set `idle` while this session is active; ask the user or end the turn instead.',
     '• `mcp__kobo-tasks__schedule_wakeup` / `mcp__kobo-tasks__cancel_wakeup` to schedule (or cancel) a follow-up session.',
     'Each tool carries its own "WHEN to use" guidance in its description — follow it.',
+    'Only one agent edits the worktree at a time: do not run background subagents that modify files while you or another subagent modify files too. Parallel read-only subagents (search, analysis, review) are fine. Wait for a file-editing subagent to finish before editing or running tests yourself, and remember that changes appearing in the worktree may come from your own subagents.',
 ].join('\n');
 export function buildCodexOptions(input) {
     const isResume = input.resumeFromEngineSessionId !== undefined;

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

@@ -14,10 +14,11 @@ export function hasIntegrationMcpConfig(integration, selectedKey) {
     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) {
+export function buildIntegrationMcpServers(settings, engineId, onUnavailable) {
     const servers = [];
-    // Fresh names avoid Codex recursively merging stale native config fields.
-    const launch = nanoid(12);
+    // Codex needs fresh names to avoid recursively merging stale native config.
+    // Claude needs stable tool names to preserve its prompt cache across resumes.
+    const launch = engineId === 'codex' ? nanoid(12) : 'managed';
     for (const integration of ['notion', 'sentry']) {
         if (!settings[`${integration}Enabled`])
             continue;

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

@@ -34,6 +34,14 @@ export class InterruptAgentError extends Error {
         this.name = 'InterruptAgentError';
     }
 }
+export class StopSubagentsError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'StopSubagentsError';
+    }
+}
 // ── State ──────────────────────────────────────────────────────────────────────
 /** Actual bound port of the running backend — set at startup via setBackendPort() */
 let backendPort = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000;
@@ -1377,7 +1385,7 @@ export function startAgent(workspaceId, workingDir, prompt, model, resume = fals
     // enforce read-only plan mode here, not only through its prompt.
     const readOnly = getReviewReturn(workspaceId, agentSessionId) !== null;
     const unavailableIntegrations = [];
-    const integrationServers = buildIntegrationMcpServers(getGlobalSettings(), (name) => unavailableIntegrations.push(name));
+    const integrationServers = buildIntegrationMcpServers(getGlobalSettings(), engine.id, (name) => unavailableIntegrations.push(name));
     const options = {
         workspaceId,
         workingDir,
@@ -1494,6 +1502,33 @@ export function interruptAgent(workspaceId, options = {}) {
         autoLoopService.disable(workspaceId, 'user-action');
     }
 }
+/**
+ * Stop one running sub-agent (by its canonical id: task id or tool call id)
+ * or, without id, every running sub-agent. The main turn keeps running.
+ * Returns the number of sub-agents a stop was requested for.
+ */
+export function stopSubagents(workspaceId, id) {
+    const ctrl = controllers.get(workspaceId);
+    if (!ctrl) {
+        throw new StopSubagentsError(`No agent running for workspace '${workspaceId}'`, 'no_agent_running');
+    }
+    let stopped;
+    try {
+        stopped = ctrl.stopSubagents(id === undefined ? undefined : [id]);
+    }
+    catch (err) {
+        // A controller whose engine has not started yet has nothing to stop.
+        const message = err instanceof Error ? err.message : String(err);
+        throw new StopSubagentsError(`No agent running for workspace '${workspaceId}': ${message}`, 'no_agent_running');
+    }
+    if (stopped === undefined) {
+        throw new StopSubagentsError(`The agent engine of workspace '${workspaceId}' cannot stop a single sub-agent`, 'unsupported');
+    }
+    if (id !== undefined && stopped === 0) {
+        throw new StopSubagentsError(`Sub-agent '${id}' is not running for workspace '${workspaceId}'`, 'subagent_not_running');
+    }
+    return stopped;
+}
 /** Bound the caller's wait, retaining ownership until actual engine shutdown. */
 export const STOP_AGENT_TIMEOUT_MS = 15_000;
 async function stopController(workspaceId, ctrl, cause = 'user') {

package/dist/server/services/agent/session-controller.js

@@ -121,6 +121,18 @@ export class SessionController {
             throw new Error('SessionController not started');
         this._engineProcess.interrupt();
     }
+    /**
+     * Stop running sub-agents without interrupting the main turn. Returns the
+     * number of sub-agents a stop was requested for, or `undefined` when the
+     * engine cannot stop a single sub-agent.
+     */
+    stopSubagents(ids) {
+        if (!this._engineProcess)
+            throw new Error('SessionController not started');
+        if (typeof this._engineProcess.stopSubagents !== 'function')
+            return undefined;
+        return this._engineProcess.stopSubagents(ids);
+    }
     stop() {
         if (!this._stopPromise) {
             this._stopPromise = this.stopEngine().catch((err) => {

package/dist/server/services/engine-handoff-service.js

@@ -1,41 +1,137 @@
-import { execFileSync } from 'node:child_process';
 import { getDb } from '../db/index.js';
-function runGit(worktreePath, args) {
+import { getWorkingTreeDiffStatsAsync, getWorkingTreePorcelainAsync } from '../utils/git-ops.js';
+const MAX_RECENT_MESSAGES = 6;
+const MAX_HISTORY_ROWS = 10_000;
+const MAX_MESSAGE_CHARS = 2_000;
+const MAX_CONVERSATION_CHARS = 12_000;
+const TRUNCATED = '[Earlier text omitted]\n';
+/** Normalized text events are deltas; a non-streaming snapshot is complete. */
+function readableFragment(row) {
     try {
-        return execFileSync('git', args.split(' '), { cwd: worktreePath, encoding: 'utf8', timeout: 10_000 }).trim();
+        const payload = JSON.parse(row.payload);
+        if (!payload || typeof payload !== 'object')
+            return null;
+        if (row.type === 'user:message' &&
+            typeof payload.content === 'string' &&
+            (payload.sender === undefined || payload.sender === 'user')) {
+            return { key: `user:${row.id}`, role: 'user', text: payload.content, complete: true };
+        }
+        if (row.type === 'agent:event' && payload.kind === 'message:text' && typeof payload.text === 'string') {
+            return {
+                // A resumed/native session may reuse the same message id elsewhere.
+                key: JSON.stringify([row.session_id, typeof payload.messageId === 'string' ? payload.messageId : row.id]),
+                role: 'assistant',
+                text: payload.text,
+                complete: payload.streaming === false,
+            };
+        }
     }
     catch {
-        return '';
+        // Historical damaged rows are not evidence of a conversation message.
     }
+    return null;
+}
+function boundedText(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const marker = '\n[Middle text omitted]\n';
+    const available = Math.max(0, limit - marker.length);
+    const first = Math.ceil(available / 2);
+    return `${text.slice(0, first)}${marker}${text.slice(-(available - first))}`.slice(0, limit);
 }
 function recentConversation(workspaceId, sessionId) {
-    const rows = getDb()
-        .prepare(`SELECT type, payload FROM ws_events
-       WHERE workspace_id = ? AND (? IS NULL OR session_id = ?)
-         AND (type = 'user:message' OR (type = 'agent:event' AND json_extract(payload, '$.kind') = 'message:text'))
-       ORDER BY rowid DESC LIMIT 6`)
-        .all(workspaceId, sessionId ?? null, sessionId ?? null);
-    return rows
-        .reverse()
-        .flatMap((row) => {
-        try {
-            const payload = JSON.parse(row.payload);
-            const text = typeof payload.content === 'string' ? payload.content : typeof payload.text === 'string' ? payload.text : '';
-            return text ? [text.slice(0, 1600)] : [];
+    const db = getDb();
+    const filter = 'workspace_id = ? AND (? IS NULL OR session_id = ?)';
+    const parameters = [workspaceId, sessionId ?? null, sessionId ?? null];
+    // Pin the most recent real user message independently of streaming volume.
+    const userRows = db
+        .prepare(`SELECT rowid AS ordinal, id, type, payload, session_id FROM ws_events
+       WHERE ${filter} AND type = 'user:message' ORDER BY rowid DESC`)
+        .iterate(...parameters);
+    let latestUser;
+    for (const row of userRows) {
+        const fragment = readableFragment(row);
+        if (!fragment?.text)
+            continue;
+        latestUser = { ...fragment, ordinal: row.ordinal, truncated: false };
+        break;
+    }
+    const rows = db
+        .prepare(`SELECT rowid AS ordinal, id, type, payload, session_id FROM ws_events
+       WHERE ${filter} AND type IN ('user:message', 'agent:event')
+       ORDER BY rowid DESC LIMIT ?`)
+        .iterate(...parameters, MAX_HISTORY_ROWS + 1);
+    const messages = new Map();
+    let scanned = 0;
+    let historyTruncated = false;
+    for (const row of rows) {
+        if (++scanned > MAX_HISTORY_ROWS) {
+            historyTruncated = true;
+            break;
         }
-        catch {
-            return [];
+        const fragment = readableFragment(row);
+        if (!fragment?.text)
+            continue;
+        const existing = messages.get(fragment.key);
+        if (existing) {
+            existing.ordinal = row.ordinal;
+            if (existing.complete)
+                continue;
+            const merged = fragment.text + existing.text;
+            existing.text = merged.slice(-MAX_MESSAGE_CHARS);
+            existing.truncated ||= merged.length > MAX_MESSAGE_CHARS;
+            existing.complete = fragment.complete;
         }
-    })
-        .join('\n\n');
+        else if (messages.size < MAX_RECENT_MESSAGES) {
+            messages.set(fragment.key, {
+                ...fragment,
+                ordinal: row.ordinal,
+                text: fragment.text.slice(-MAX_MESSAGE_CHARS),
+                truncated: fragment.text.length > MAX_MESSAGE_CHARS,
+            });
+        }
+    }
+    const selected = [];
+    const warning = historyTruncated
+        ? '\n\n[Conversation history truncated; recover older context from the source session.]'
+        : '';
+    let remaining = MAX_CONVERSATION_CHARS - warning.length;
+    if (latestUser) {
+        const pinned = `Latest user instruction:\n${boundedText(latestUser.text, 6_000)}`;
+        selected.push({ ordinal: latestUser.ordinal, text: pinned });
+        remaining -= pinned.length + 2;
+        messages.delete(latestUser.key);
+    }
+    const newestFirst = [...messages.values()].sort((a, b) => b.ordinal - a.ordinal);
+    for (const message of newestFirst) {
+        const label = message.role === 'assistant' ? 'Assistant:\n' : 'User:\n';
+        if (remaining <= label.length + TRUNCATED.length + 2)
+            break;
+        const text = message.truncated ? TRUNCATED + message.text : message.text;
+        const rendered = label + boundedText(text, Math.min(MAX_MESSAGE_CHARS, remaining - label.length - 2));
+        selected.push({ ordinal: message.ordinal, text: rendered });
+        remaining -= rendered.length + 2;
+    }
+    return (selected
+        .sort((a, b) => a.ordinal - b.ordinal)
+        .map((message) => message.text)
+        .join('\n\n') + warning);
 }
 /** Build a deterministic, secret-free handoff for a fresh session on another engine. */
-export function buildEngineHandoff(workspace, sourceEngine, targetEngine, sourceSessionId) {
+export async function buildEngineHandoff(workspace, sourceEngine, targetEngine, sourceSessionId) {
     const taskLines = workspace.tasks.length
         ? workspace.tasks.map((task) => `- [${task.status === 'done' ? 'x' : ' '}] ${task.title}`).join('\n')
         : '- No Kōbō task recorded.';
-    const changedFiles = runGit(workspace.worktreePath, 'status --short') || 'No uncommitted changes detected.';
-    const diffStat = runGit(workspace.worktreePath, 'diff --stat') || 'No uncommitted diff stat available.';
+    const [status, diff] = await Promise.allSettled([
+        getWorkingTreePorcelainAsync(workspace.worktreePath),
+        getWorkingTreeDiffStatsAsync(workspace.worktreePath),
+    ]);
+    const changedFiles = status.status === 'fulfilled'
+        ? status.value.trim() || 'No uncommitted changes detected.'
+        : 'Git state unavailable. Verify the working tree before making changes.';
+    const diffStat = diff.status === 'fulfilled'
+        ? diff.value.trim() || 'No uncommitted diff stat available.'
+        : 'Git state unavailable. Run git diff --stat to recover the summary.';
     const history = recentConversation(workspace.id, sourceSessionId) || 'No recent conversation message available.';
     return `# Kōbō engine handoff\n\nYou are taking over this workspace from ${sourceEngine} using ${targetEngine}. Work in the existing worktree and verify the repository state before making changes.\n\n## Objective\n${workspace.description ?? workspace.name}\n\n## Tasks\n${taskLines}\n\n## Git state\n- Branch: ${workspace.workingBranch}\n- Base: ${workspace.sourceBranch}\n- Worktree: ${workspace.worktreePath}\n\nChanged files:\n\`\`\`\n${changedFiles}\n\`\`\`\n\nDiff summary:\n\`\`\`\n${diffStat}\n\`\`\`\n\n## Recent conversation\n${history}\n\n## Recover more context\nIf this handoff is insufficient, use \`kobo__read_workspace_events_csv\` to read the previous workspace conversation in pages (optionally filter by \`session_id\`). Use \`kobo__search_codebase\` to find a precise past decision or user request. Read only the context needed, then continue the task.\n`;
 }