@loicngr/kobo 1.11.43 → 1.11.45

package/AGENTS.md

@@ -116,6 +116,7 @@ src/
 | `tasks` | workspace sub-items: title, status, `is_acceptance_criterion`, sort_order; CASCADE DELETE on workspace |
 | `agent_sessions` | agent-engine sessions: pid where applicable, engine session id, status, timestamps, model, and name |
 | `ws_events` | persisted WebSocket events for replay on reconnect: type, payload, session_id, created_at |
+| `pending_review_returns` | one-shot return from a review to its original session and LLM configuration (migration v44) |
 | `pending_wakeups` | one-row-per-workspace scheduler for the `schedule_wakeup` MCP tool: target_at (ISO UTC), prompt, reason; CASCADE DELETE on workspace |
 | `pending_quota_backoffs` | persisted quota retries and their attempt counts |
 | `pending_crons` | recurring workspace schedules and their next run |
@@ -135,7 +136,11 @@ src/
 
 `worktree_purged_at` + `worktree_purge_restore_data` drive the disk-space purge feature (see [Worktree purge](#worktree-purge) below): when set, the workspace's worktree folder has been removed from disk but the chat history is preserved. `worktree_purge_restore_data` is a JSON blob (`{ prNumber, prUrl, forge, mergeCommitSha, originalWorktreePath, originalSourceBranch, originalWorkingBranch }`) captured at purge time for future "Restore" UX. Both fields are cleared automatically by the pr-watcher when the worktree folder reappears on disk.
 
-`auto_loop` (bool, default 0), `auto_loop_ready` (bool, default 0) and `no_progress_streak` (int, default 0) drive the auto-loop feature: when `auto_loop=1`, `session:ended` triggers `auto-loop-service.onSessionEnded` which either spawns the next iteration via a fresh `startAgent(resume=false)`, disables with `reason='completed'` (no pending tasks), or disables with `reason='stall'` (3 consecutive sessions without a task completed). Archive + delete both auto-disable.
+`auto_loop` preserves the user's execution intent. `auto_loop_runs` (migration v45) stores phase (`grooming | execution | finalization`), operational state (`active | waiting | blocked | completed | stopped`), iteration count and diagnostic recovery. `auto_loop_progress` records monotone task milestones; metadata changes are not progress. After three stagnant iterations, run one diagnostic and two further attempts, then block explicitly without clearing intent. Quotas wait for their actual reset, including multi-day windows; only transient failures use the retry cap. Archived/deleted workspaces disable the loop.
+
+Tasks have `role` (`work | finalization`) and structured `verification`. MCP and HTTP share transactional task mutations. An auto-loop task cannot become done without passing reported checks. Finalization runs after all other tasks/criteria, is invalidated by scope changes, and is mandatory before completion. The proof is agent-reported evidence, not server-side execution of arbitrary commands.
+
+`auto_loop_messages` durably queues next-iteration instructions, independently of engine session ids. A dispatch interrupted before confirmed completion becomes `unknown`, requiring explicit acknowledgement or retry. Unknown or in-flight instructions prevent completion. Actual engine closure (`EngineProcess.closed`), not a logical end event alone, releases controller ownership and permits the next writer.
 
 `brainstorm_model` (nullable, set only at creation) lets a workspace created with `auto_loop=1` run its initial brainstorming session on a different model than the auto-loop iterations that follow, while staying on the same engine. `POST /api/workspaces` uses it for the very first `startAgent` call only; every subsequent auto-loop iteration (`auto-loop-service.ts`'s `spawnNextIteration`) always reads `model`, unchanged. The switch to `model` takes effect once that first live session ends naturally — not at the `[BRAINSTORM_COMPLETE]` marker, since the same session keeps running under `brainstorm_model` until it stops on its own.
 
@@ -259,6 +264,74 @@ 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 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.
+
+`StartReviewDialog.vue` uses the shared model/effort/permission catalogues. Changed
+settings force a new session on both client and server. `review-service.ts`
+validates before side effects, waits for confirmed shutdown, then applies the
+selected configuration and launches the review. Without a return request, these
+settings remain the workspace defaults. Legacy requests retain their behavior.
+
+The optional `returnToSession` flag captures the exact resumable original session.
+`pending_review_returns` persists its configuration and the review session id
+before switching engines. The orchestrator intercepts a successful review end
+(including watchdog closure without a nonzero exit), restores configuration and
+resumes that exact native conversation with the reviewer's final text report.
+Resume selection is scoped to the target engine; never pass a reviewer's native
+conversation id to the original engine, even after cancellation or restart.
+The report reassembles text deltas/final snapshots, is bounded to 24,000 characters,
+and links back to the complete review session through the conversation tool.
+The receiving agent is asked to summarize and await instructions before fixes.
+The intent is consumed before delivery, preventing repeated ends from sending twice.
+Errors restore settings without automatically resuming; explicit stop cancels the
+return. Startup restores interrupted-review settings without replaying a possibly
+already-delivered handoff. Preserve these guards and the auto-loop interception.
+`workspace:configuration` is ephemeral and updates all four LLM settings across tabs.
+
 ### Delete confirmation
 
 The workspace deletion dialog requires the exact `workingBranch`, not the editable

package/CHANGELOG.md

@@ -4,6 +4,17 @@ 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
+- fix(auto-loop): preserve mission intent until verified completion
+- feat(review): configure review LLM and return to original session
+
 ## 1.11.43
 
 - fix(workspaces): refine watchdog stops and deletion confirmation

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,12 +1,16 @@
+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';
 import * as cronService from '../server/services/cron-service.js';
 import * as settingsService from '../server/services/settings-service.js';
+import { createTaskRecord, deleteTaskRecord, updateTaskRecord, } from '../server/services/task-mutations.js';
 import { slugifyProjectName } from '../server/utils/project-slug.js';
 import { ensureDirectoryInside, resolveExistingPathInside } from '../server/utils/safe-path.js';
 import { resolveWorkspaceWorktreePath } from '../server/utils/worktree-paths.js';
 import { MASKED_SECRET, SECRET_GLOBAL_KEYS } from '../shared/consts.js';
+import { parseTaskVerification } from '../shared/task-verification.js';
 /** Allowed task status values. */
 export const VALID_TASK_STATUSES = ['pending', 'in_progress', 'done'];
 function rowToDto(row) {
@@ -15,12 +19,15 @@ function rowToDto(row) {
         title: row.title,
         status: row.status,
         is_acceptance_criterion: row.is_acceptance_criterion === 1,
+        sort_order: row.sort_order,
+        role: row.role,
+        verification: parseTaskVerification(row.verification),
     };
 }
 /** Return all tasks for a workspace, ordered by sort_order. */
 export function listTasksHandler(db, workspaceId) {
     const rows = db
-        .prepare('SELECT id, title, status, is_acceptance_criterion FROM tasks WHERE workspace_id = ? ORDER BY sort_order ASC')
+        .prepare('SELECT * FROM tasks WHERE workspace_id = ? ORDER BY sort_order ASC, rowid ASC')
         .all(workspaceId);
     return rows.map(rowToDto);
 }
@@ -81,86 +88,38 @@ export function setWorkspaceAgentDescriptionHandler(db, workspaceId, args) {
     }
     return { ok: true, description: stored };
 }
-/** Set a task's status to "done" and return the updated task. */
-export function markTaskDoneHandler(db, workspaceId, taskId) {
-    const now = new Date().toISOString();
-    const result = db
-        .prepare('UPDATE tasks SET status = ?, updated_at = ? WHERE id = ? AND workspace_id = ?')
-        .run('done', now, taskId, workspaceId);
-    if (result.changes === 0) {
-        throw new Error(`Task '${taskId}' not found in workspace '${workspaceId}'`);
-    }
-    const row = db
-        .prepare('SELECT id, title, status, is_acceptance_criterion FROM tasks WHERE id = ?')
-        .get(taskId);
+/** Set a task's status to done; auto-loop tasks require successful evidence. */
+export function markTaskDoneHandler(db, workspaceId, taskId, verification) {
+    const row = updateTaskRecord(db, workspaceId, taskId, {
+        status: 'done',
+        ...(verification !== undefined ? { verification } : {}),
+    });
     return { success: true, task: rowToDto(row) };
 }
-/** Create a new task appended at the end of the workspace's task list. */
+/** Create a task at an explicit position or append it to the list. */
 export function createTaskHandler(db, workspaceId, data) {
-    if (!data.title?.trim()) {
-        throw new Error('title is required');
-    }
-    // Verify workspace exists
-    const ws = db.prepare('SELECT id FROM workspaces WHERE id = ?').get(workspaceId);
-    if (!ws) {
-        throw new Error(`Workspace '${workspaceId}' not found`);
-    }
-    const id = nanoid();
-    const now = new Date().toISOString();
-    const isAC = data.is_acceptance_criterion ? 1 : 0;
-    // Append at the end: max(sort_order) + 1
-    const maxRow = db
-        .prepare('SELECT COALESCE(MAX(sort_order), -1) AS max FROM tasks WHERE workspace_id = ?')
-        .get(workspaceId);
-    const sortOrder = maxRow.max + 1;
-    db.prepare('INSERT INTO tasks (id, workspace_id, title, status, is_acceptance_criterion, sort_order, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(id, workspaceId, data.title.trim(), 'pending', isAC, sortOrder, now, now);
-    const row = db.prepare('SELECT id, title, status, is_acceptance_criterion FROM tasks WHERE id = ?').get(id);
-    return rowToDto(row);
+    return rowToDto(createTaskRecord(db, workspaceId, {
+        title: data.title,
+        isAcceptanceCriterion: data.is_acceptance_criterion,
+        sortOrder: data.sort_order,
+        afterTaskId: data.after_task_id,
+        role: data.role,
+    }));
 }
-/** Update one or more fields of an existing task (title, status, or acceptance criterion flag). */
+/** Update task fields atomically, including insertion order and verification. */
 export function updateTaskHandler(db, workspaceId, taskId, data) {
-    // Verify task belongs to workspace
-    const existing = db.prepare('SELECT id FROM tasks WHERE id = ? AND workspace_id = ?').get(taskId, workspaceId);
-    if (!existing) {
-        throw new Error(`Task '${taskId}' not found in workspace '${workspaceId}'`);
-    }
-    const sets = [];
-    const values = [];
-    if (data.title !== undefined) {
-        if (!data.title.trim())
-            throw new Error('title cannot be empty');
-        sets.push('title = ?');
-        values.push(data.title.trim());
-    }
-    if (data.status !== undefined) {
-        if (!VALID_TASK_STATUSES.includes(data.status)) {
-            throw new Error(`Invalid status '${data.status}'. Must be one of: ${VALID_TASK_STATUSES.join(', ')}`);
-        }
-        sets.push('status = ?');
-        values.push(data.status);
-    }
-    if (data.is_acceptance_criterion !== undefined) {
-        sets.push('is_acceptance_criterion = ?');
-        values.push(data.is_acceptance_criterion ? 1 : 0);
-    }
-    if (sets.length === 0) {
-        throw new Error('No fields to update (provide title, status, or is_acceptance_criterion)');
-    }
-    sets.push('updated_at = ?');
-    values.push(new Date().toISOString());
-    values.push(taskId);
-    db.prepare(`UPDATE tasks SET ${sets.join(', ')} WHERE id = ?`).run(...values);
-    const row = db
-        .prepare('SELECT id, title, status, is_acceptance_criterion FROM tasks WHERE id = ?')
-        .get(taskId);
-    return rowToDto(row);
+    return rowToDto(updateTaskRecord(db, workspaceId, taskId, {
+        title: data.title,
+        status: data.status,
+        isAcceptanceCriterion: data.is_acceptance_criterion,
+        sortOrder: data.sort_order,
+        afterTaskId: data.after_task_id,
+        verification: data.verification,
+    }));
 }
-/** Permanently delete a task from a workspace. */
+/** Permanently delete a task from a workspace and invalidate its final review. */
 export function deleteTaskHandler(db, workspaceId, taskId) {
-    const result = db.prepare('DELETE FROM tasks WHERE id = ? AND workspace_id = ?').run(taskId, workspaceId);
-    if (result.changes === 0) {
-        throw new Error(`Task '${taskId}' not found in workspace '${workspaceId}'`);
-    }
+    deleteTaskRecord(db, workspaceId, taskId);
     return { success: true, task_id: taskId };
 }
 /** Read the dev-server status for a workspace directly from the database. */
@@ -310,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;
@@ -113,20 +115,63 @@ async function backendRequest(method, pathname, body) {
     return text ? JSON.parse(text) : null;
 }
 const server = new Server({ name: 'kobo-tasks', version: '1.0.0' }, { capabilities: { tools: {} } });
+const TASK_VERIFICATION_SCHEMA = {
+    type: 'object',
+    description: 'Required to complete an auto-loop task. Describe checks actually performed; every check must be passed for done. Record failed/not_run checks only on an unfinished task.',
+    properties: {
+        method: { type: 'string', minLength: 1 },
+        summary: { type: 'string', minLength: 1 },
+        checks: {
+            type: 'array',
+            minItems: 1,
+            items: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', minLength: 1 },
+                    status: { type: 'string', enum: ['passed', 'failed', 'not_run'] },
+                },
+                required: ['name', 'status'],
+            },
+        },
+    },
+    required: ['method', 'summary', 'checks'],
+};
+const TASK_ORDER_PROPERTIES = {
+    sort_order: {
+        type: 'integer',
+        minimum: 0,
+        description: 'Insert/move at this order, shifting siblings. Omit to append on creation. Mutually exclusive with after_task_id.',
+    },
+    after_task_id: {
+        type: 'string',
+        description: 'Insert/move immediately after this task in the same workspace, preserving the remaining order.',
+    },
+};
 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 and status. 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.',
+        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.',
         inputSchema: { type: 'object', properties: {}, required: [] },
         annotations: { readOnlyHint: true, openWorldHint: false },
     },
     {
         name: 'mark_task_done',
-        description: 'CALL AS SOON AS a task or acceptance criterion is finished AND verified (tests pass, feature works, diff committed). Do not wait for the end of the turn — the user watches progress live and marking each item as it completes is the primary signal Kōbō uses to track you.',
+        description: 'CALL AS SOON AS a task or acceptance criterion is finished AND verified by checks actually performed. Auto-loop requires structured verification evidence with all checks passed. Never mark done if required checks failed or were not run. Finalization also requires all work tasks and criteria done. Do not wait for the end of the turn — the user watches progress live and marking each item as it completes is the primary signal Kōbō uses to track you.',
         inputSchema: {
             type: 'object',
             properties: {
                 task_id: { type: 'string', description: 'Task id from list_tasks.' },
+                verification: TASK_VERIFICATION_SCHEMA,
             },
             required: ['task_id'],
         },
@@ -140,10 +185,16 @@ const WORKSPACE_SCOPED_TOOLS = [
     },
     {
         name: 'create_task',
-        description: 'CALL WHEN you discover follow-up work that was not in the original list and needs to stick around (e.g. "refactor this helper later", "add a test for edge case"). Appends at the end of the list. Do not use it for ephemeral internal notes — prefer log_thought for those.',
+        description: 'CALL WHEN you discover follow-up work that was not in the original list and needs to stick around (e.g. "refactor this helper later", "add a test for edge case"). Appends by default; use after_task_id for a dependent check immediately after its parent. Use role finalization for the final verification gate. Do not use it for ephemeral internal notes — prefer log_thought for those.',
         inputSchema: {
             type: 'object',
             properties: {
+                ...TASK_ORDER_PROPERTIES,
+                role: {
+                    type: 'string',
+                    enum: ['work', 'finalization'],
+                    description: 'Default work. Finalization is the final verification gate and cannot finish while work/criteria remain open.',
+                },
                 title: { type: 'string', description: 'Short, imperative title (e.g. "Add retry to fetchUser").' },
                 is_acceptance_criterion: {
                     type: 'boolean',
@@ -161,6 +212,8 @@ const WORKSPACE_SCOPED_TOOLS = [
             type: 'object',
             properties: {
                 task_id: { type: 'string', description: 'Task id from list_tasks.' },
+                ...TASK_ORDER_PROPERTIES,
+                verification: TASK_VERIFICATION_SCHEMA,
                 title: { type: 'string', description: 'New title (optional).' },
                 status: {
                     type: 'string',
@@ -371,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: {
@@ -568,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) }] };
@@ -600,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.');
@@ -612,7 +679,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const taskId = a.task_id;
             if (!taskId)
                 return fail('task_id parameter is required');
-            const result = markTaskDoneHandler(db, workspaceId, taskId);
+            const result = markTaskDoneHandler(db, workspaceId, taskId, a.verification);
             void notifyBackend(taskId);
             return ok(result);
         }
@@ -627,7 +694,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return fail('title parameter is required');
             const task = createTaskHandler(db, workspaceId, {
                 title,
+                role: a.role,
                 is_acceptance_criterion: a.is_acceptance_criterion,
+                sort_order: a.sort_order,
+                after_task_id: a.after_task_id,
             });
             void notifyTasksUpdated();
             return ok(task);
@@ -639,7 +709,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const task = updateTaskHandler(db, workspaceId, taskId, {
                 title: a.title,
                 status: a.status,
+                verification: a.verification,
                 is_acceptance_criterion: a.is_acceptance_criterion,
+                sort_order: a.sort_order,
+                after_task_id: a.after_task_id,
             });
             void notifyTasksUpdated();
             return ok(task);

package/dist/server/db/auto-loop-schema.js

@@ -0,0 +1,44 @@
+/** Shared by fresh installs and the append-only upgrade. */
+export function initAutoLoopSchema(db) {
+    const columns = db.prepare('PRAGMA table_info(tasks)').all();
+    if (columns.length) {
+        if (!columns.some((c) => c.name === 'role'))
+            db.exec("ALTER TABLE tasks ADD COLUMN role TEXT NOT NULL DEFAULT 'work'");
+        if (!columns.some((c) => c.name === 'verification'))
+            db.exec('ALTER TABLE tasks ADD COLUMN verification TEXT');
+        if (columns.some((c) => c.name === 'title')) {
+            db.exec("UPDATE tasks SET role = 'finalization' WHERE title LIKE '[FINAL] %' AND role = 'work'");
+        }
+    }
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS auto_loop_runs (
+      workspace_id TEXT PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+      phase TEXT NOT NULL DEFAULT 'grooming',
+      state TEXT NOT NULL DEFAULT 'waiting',
+      reason TEXT,
+      iteration INTEGER NOT NULL DEFAULT 0,
+      diagnostic_attempts INTEGER NOT NULL DEFAULT 0,
+      current_task_id TEXT,
+      current_session_id TEXT,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS auto_loop_progress (
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      milestone INTEGER NOT NULL DEFAULT 0,
+      PRIMARY KEY (workspace_id, task_id)
+    );
+    CREATE TABLE IF NOT EXISTS auto_loop_messages (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      client_message_id TEXT NOT NULL,
+      content TEXT NOT NULL,
+      source TEXT,
+      state TEXT NOT NULL DEFAULT 'pending',
+      session_id TEXT,
+      created_at TEXT NOT NULL,
+      UNIQUE (workspace_id, client_message_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_auto_loop_messages_pending ON auto_loop_messages(workspace_id, state, id);
+  `);
+}

package/dist/server/db/migrations.js

@@ -1,6 +1,9 @@
+import { initAutoLoopSchema } from './auto-loop-schema.js';
 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 = [
     {
@@ -744,6 +747,21 @@ export const migrations = [
     },
     { version: 42, name: 'index-logical-search-messages', migrate: initSearchSchema },
     { 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/review-return-schema.js

@@ -0,0 +1,10 @@
+export function initReviewReturnSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS pending_review_returns (
+    workspace_id TEXT PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+    review_session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+    original_session_id TEXT NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+    original_configuration TEXT NOT NULL,
+    review_configuration TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  )`);
+}

package/dist/server/db/schema.js

@@ -1,5 +1,8 @@
+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(`
@@ -68,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 (
@@ -225,4 +229,7 @@ export function initSchema(db) {
   `);
     initSearchSchema(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');`);
+}