@loicngr/kobo 1.7.3 → 1.7.5

package/README.md

@@ -31,9 +31,10 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Resizable right drawer** — drag-to-resize horizontally and vertically, with tab state and split ratio persisted to localStorage
 - **Soft interrupt** — pause an agent mid-execution (SIGINT, like pressing Escape in Claude Code) without killing the process; the agent stops the current tool and waits for the next message
 - **Archive instead of delete** — soft-remove workspaces without losing the worktree, branches, or history; unarchive restores the exact pre-archive state
-- **Auto-loop mode** — opt-in, per-workspace: when enabled, Kōbō spawns a fresh Claude session for the next pending task after every `session:ended`, walking through the task list until all are `done`. Stops automatically on error, on stall (3 consecutive sessions with no task completed), or when the user clicks Stop. A grooming step (`/kobo-prep-autoloop`) ensures tasks are atomic before the loop runs; Notion-imported workspaces with both todos and acceptance criteria are auto-unlocked. **E2E grooming** — when a project declares an E2E framework in Settings (Cypress, Playwright, Vitest, etc.), the grooming phase injects an `[E2E] ` test sub-task between every parent task; each iteration then runs the matching E2E suite as part of its acceptance check
+- **Auto-loop mode** — opt-in, per-workspace: when enabled, Kōbō spawns a fresh Claude session for the next pending task after every `session:ended`, walking through the task list until all are `done`. Stops automatically on error, on stall (3 consecutive sessions with no task completed), or when the user clicks Stop. A grooming step (`/kobo-prep-autoloop`) ensures tasks are atomic before the loop runs; Notion-imported workspaces with both todos and acceptance criteria are auto-unlocked. **E2E grooming** — when a project declares an E2E framework in Settings (Cypress, Playwright, Vitest, etc.), the grooming phase injects an `[E2E] ` test sub-task between every parent task; each iteration then runs the matching E2E suite as part of its acceptance check. **Sidebar progress chip** — auto-loop workspaces show an `X / Y tâches` badge in the workspace list, fed by the same task counts used by the in-page chip
 - **Attach existing worktrees** — Kōbō detects orphan git worktrees for the selected project (created outside Kōbō, or left over from an earlier install) and lets you attach them to a new workspace from the creation form, picking up the existing branch and folder instead of cloning a new one
-- **Quota-aware retry backoff** — when a Claude rate limit is hit mid-session, Kōbō schedules the retry at the actual reset time reported by the API (via `rate_limit.info.buckets[].resetsAt`), falling back to a 15 → 30 → 60 → 180 → 300 min ladder only when the reset info is missing or implausible
+- **Persistent quota backoff** — when a Claude rate limit is hit mid-session, Kōbō schedules the retry at the actual reset time reported by the API (via `rate_limit.info.buckets[].resetsAt`), falling back to the OAuth usage poller, then to a 15 → 30 → 60 → 180 → 300 min ladder when both are missing. The pending backoff is **persisted in SQLite** and re-armed on server restart, so nothing is lost if the host reboots mid-window. A live banner counts down to the reset and lets the user cancel the wait. Only auto-loop workspaces resume automatically — others stay in `quota` status awaiting a manual nudge
+- **Workspace description fields** — every workspace has TWO independent description fields. The user-side `description` is editable via the header input or right-click **Modifier la description**, and stays under the user's control (the agent cannot overwrite it). The agent maintains its own `agent_description` via the `set_workspace_agent_description` MCP tool to broadcast a live status (e.g. "Investigating SERVICE-1600 → enriching local Notion file"). Both are visible: the sidebar shows `agent_description` when set, falling back to the user `description`; the workspace header shows the user input plus an italic read-only line for the agent's current focus
 - **Scheduled wakeups** — the `ScheduleWakeup` tool is honoured server-side: Kōbō persists the wakeup in SQLite, rehydrates on restart, and respawns the agent with `--resume` at the target time
 
 ## Tech stack
@@ -101,8 +102,8 @@ npm start           # runs the compiled server
 ### Test & lint
 
 ```bash
-npm test            # backend vitest suite (950+ tests)
-npm run test:client # client vitest suite (Pinia stores + pure utils, 85+ tests)
+npm test            # backend vitest suite (1200+ tests)
+npm run test:client # client vitest suite (Pinia stores + pure utils, 230+ tests)
 npm run test:all    # backend + client suites
 npm run lint        # biome check (lint + format verification)
 npm run lint:fix    # biome check with safe auto-fixes
@@ -229,6 +230,7 @@ src/
 │   │   │   └── engines/claude-code/        # spawn + NDJSON stream-parser + args-builder + mcp-config + capabilities
 │   │   ├── content-migration-service.ts    # legacy ws_events → normalised AgentEvent rows, with DB backup
 │   │   ├── usage/                          # pluggable quota provider, 60s poller, persistence, WS broadcast
+│   │   ├── quota-backoff-service.ts        # persisted Claude rate-limit backoff timers (re-armed on restart)
 │   │   └── …                               # workspace, dev-server, ws, notion, sentry, settings, pr-template
 │   ├── routes/                             # Hono handlers (workspaces, engines, migration, templates, usage, …)
 │   └── utils/                              # git-ops, process-tracker, paths
@@ -252,18 +254,28 @@ See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, W
 
 | Table | Purpose |
 |---|---|
-| `workspaces` | the unit of work — branch, `worktree_path`, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, … |
+| `workspaces` | the unit of work — branch, `worktree_path`, status, model, engine, `archived_at`, `favorited_at`, `tags`, Notion link, plus the two independent description columns (`description` user-controlled, `agent_description` agent-controlled), … |
 | `tasks` | workspace sub-items — tasks and acceptance criteria |
 | `agent_sessions` | agent runs — pid, `engine_session_id`, lifecycle |
 | `ws_events` | persisted WebSocket events (chat history, `agent:event` stream, user messages) for replay on reconnect |
 | `usage_snapshots` | latest quota snapshot per provider (one row per `provider_id`) — populated by the 60s polling loop, used for cold-start hydration of the chat-footer quota badge |
+| `pending_wakeups` | one row per scheduled wakeup, target time and resume context, re-armed on server restart |
+| `pending_quota_backoffs` | one row per workspace currently waiting on a Claude rate-limit reset, target time + reset metadata + retry count, re-armed on server restart |
 
 ## MCP server
 
-Each workspace spawns its own `kobo-tasks` MCP server as a child process of the Claude Code agent. It exposes two tools:
+Each workspace spawns its own `kobo-tasks` MCP server as a child process of the Claude Code agent. It exposes a curated tool surface tailored for agents working inside a Kōbō workspace, grouped by intent:
 
-- `list_tasks()` — returns all tasks & acceptance criteria for the current workspace with their IDs and status
-- `mark_task_done(task_id)` — marks a task as done and notifies the backend over HTTP so the UI updates live
+- **Tasks** — `list_tasks`, `create_task`, `update_task`, `delete_task`, `mark_task_done`
+- **Workspace metadata** — `get_workspace_info` (returns name, branch, status, both `description` and `agentDescription`, etc.), `set_workspace_agent_description` (live status the user sees in the sidebar without opening the workspace), `set_workspace_status`
+- **Auto-loop** — `mark_auto_loop_ready` (flip the grooming gate when the brainstorm step is done)
+- **Git** — `get_git_info` (branch, commit count, dirty state)
+- **Dev server** — `get_dev_server_status`, `start_dev_server`, `stop_dev_server`, `get_dev_server_logs`
+- **External sources** — `get_notion_ticket`, `get_settings`
+- **Documents & search** — `list_documents`, `read_document`, `log_thought`, `search_codebase`, `list_workspace_images`
+- **Scheduling & telemetry** — `schedule_wakeup`, `cancel_wakeup`, `get_session_usage`
+
+State-mutating tools that change UI-visible data (tasks, agent description, auto-loop readiness) write directly to SQLite for low latency, then fire-and-forget a `notify-*` HTTP call to the backend so the WebSocket layer broadcasts the change to every connected client.
 
 The MCP server reads and writes the same SQLite database as the main backend. Isolation between workspaces is enforced via the `KOBO_WORKSPACE_ID` environment variable passed at spawn time and validated on every query.
 

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

@@ -37,6 +37,29 @@ export function markAutoLoopReadyHandler(db, workspaceId) {
     db.prepare('UPDATE workspaces SET auto_loop_ready = 1 WHERE id = ?').run(workspaceId);
     return { ok: true };
 }
+/**
+ * Update the workspace's agent-side short description (≤ 200 chars). Empty /
+ * whitespace-only input clears the field (stored as NULL). This writes the
+ * `agent_description` column — a live status line owned by the agent — and
+ * leaves the user-side `description` column untouched. The handler does NOT
+ * emit a WS event; that's the route/service layer's responsibility. Live UI
+ * refresh on agent-driven updates is therefore deferred until next read.
+ */
+export function setWorkspaceAgentDescriptionHandler(db, workspaceId, args) {
+    const raw = typeof args?.description === 'string' ? args.description : '';
+    const trimmed = raw.trim();
+    if (trimmed.length > 200) {
+        return { ok: false, error: `Description must be 200 characters or fewer (got ${trimmed.length})` };
+    }
+    const stored = trimmed.length > 0 ? trimmed : null;
+    const result = db
+        .prepare('UPDATE workspaces SET agent_description = ?, updated_at = ? WHERE id = ?')
+        .run(stored, new Date().toISOString(), workspaceId);
+    if (result.changes === 0) {
+        return { ok: false, error: `Workspace '${workspaceId}' not found` };
+    }
+    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();
@@ -155,7 +178,7 @@ export function getSettingsHandler(settingsPath, projectPath) {
 /** Fetch workspace metadata from the database, computing the worktree path from project_path and working_branch. */
 export function getWorkspaceInfoHandler(db, workspaceId) {
     const row = db
-        .prepare('SELECT id, name, project_path, source_branch, working_branch, worktree_path, status, notion_url, notion_page_id, model, dev_server_status, has_unread, auto_loop, auto_loop_ready, created_at, updated_at FROM workspaces WHERE id = ?')
+        .prepare('SELECT id, name, project_path, source_branch, working_branch, worktree_path, status, notion_url, notion_page_id, description, agent_description, model, dev_server_status, has_unread, auto_loop, auto_loop_ready, created_at, updated_at FROM workspaces WHERE id = ?')
         .get(workspaceId);
     if (!row) {
         throw new Error(`Workspace '${workspaceId}' not found`);
@@ -176,6 +199,8 @@ export function getWorkspaceInfoHandler(db, workspaceId) {
         model: row.model,
         notionUrl: row.notion_url,
         notionPageId: row.notion_page_id,
+        description: row.description ?? null,
+        agentDescription: row.agent_description ?? null,
         devServerStatus: row.dev_server_status,
         hasUnread: row.has_unread === 1,
         autoLoop: row.auto_loop === 1,

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

@@ -5,7 +5,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import Database from 'better-sqlite3';
-import { createTaskHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, logThoughtHandler, markAutoLoopReadyHandler, markTaskDoneHandler, readDocumentHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
+import { createTaskHandler, deleteTaskHandler, getDevServerStatusHandler, getSessionUsageHandler, getSettingsHandler, getWorkspaceInfoHandler, listDocumentsHandler, listTasksHandler, listWorkspaceImagesHandler, logThoughtHandler, markAutoLoopReadyHandler, markTaskDoneHandler, readDocumentHandler, setWorkspaceAgentDescriptionHandler, updateTaskHandler, } from './kobo-tasks-handlers.js';
 const workspaceId = process.env.KOBO_WORKSPACE_ID;
 const dbPath = process.env.KOBO_DB_PATH;
 const settingsPath = process.env.KOBO_SETTINGS_PATH;
@@ -68,6 +68,22 @@ async function notifyAutoLoopReady() {
         console.error('[kobo-tasks-server] notify-autoloop-ready failed:', err);
     }
 }
+/**
+ * Fire-and-forget POST that lands on `/agent-description/notify-updated`,
+ * which emits the `workspace:agent-description-updated` WS event so the
+ * sidebar fallback display + the workspace header italic line refresh live
+ * across every connected client. The handler already wrote the column to DB;
+ * this call is ONLY for the event emission.
+ */
+async function notifyAgentDescriptionUpdated() {
+    try {
+        const url = `${backendUrl}/api/workspaces/${workspaceId}/agent-description/notify-updated`;
+        await fetch(url, { method: 'POST' });
+    }
+    catch (err) {
+        console.error('[kobo-tasks-server] notify-agent-description-updated failed:', err);
+    }
+}
 /** Generic HTTP request to the Kobo backend, returning parsed JSON or null. */
 async function backendRequest(method, pathname, body) {
     const url = `${backendUrl}${pathname}`;
@@ -160,6 +176,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: 'CALL EARLY in a session to confirm project path, working/source branch, worktree path, model, and notion link. Cheap read — useful when the user refers to "this workspace" or when you need the worktree path to locate files.',
             inputSchema: { type: 'object', properties: {}, required: [] },
         },
+        {
+            name: 'set_workspace_agent_description',
+            description: "Set or clear the workspace's agent-side description (≤ 200 chars). Pass an empty string to clear. The user sees this string under the workspace title in the sidebar (it takes precedence over the user-controlled `description` field). Plain text only. The current value is available via get_workspace_info as agentDescription. NOTE: there is a separate user-controlled `description` field — do NOT try to write it; it has no MCP tool.",
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    description: {
+                        type: 'string',
+                        description: 'Plain text, max 200 characters. Empty string clears the description.',
+                    },
+                },
+                required: ['description'],
+            },
+        },
         {
             name: 'get_git_info',
             description: 'CALL BEFORE creating a PR, committing in batches, or reporting progress to the user. Returns commit count ahead of source, files changed, insertions/deletions, and existing PR URL if any.',
@@ -396,6 +426,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (name === 'get_workspace_info') {
             return ok(getWorkspaceInfoHandler(db, workspaceId));
         }
+        if (name === 'set_workspace_agent_description') {
+            const description = a.description;
+            if (typeof description !== 'string')
+                return fail('description parameter is required');
+            const result = setWorkspaceAgentDescriptionHandler(db, workspaceId, { description });
+            if ('ok' in result && result.ok) {
+                void notifyAgentDescriptionUpdated();
+            }
+            return ok(result);
+        }
         if (name === 'start_dev_server') {
             const result = await backendRequest('POST', `/api/dev-server/${workspaceId}/start`);
             return ok(result);

package/dist/server/db/migrations.js

@@ -194,6 +194,55 @@ export const migrations = [
             db.prepare('ALTER TABLE pending_wakeups ADD COLUMN agent_session_id TEXT').run();
         },
     },
+    {
+        version: 19,
+        name: 'add-pending-quota-backoffs',
+        migrate: (db) => {
+            // Per-workspace quota-backoff scheduler: tracks the moment a workspace
+            // becomes eligible to retry after hitting a quota limit. Mirrors the
+            // shape of pending_wakeups (one row per workspace, FK CASCADE) but holds
+            // distinct fields (resets_at, source, retry_count) tied to the quota
+            // detection layer (rate-limit info, usage API, fallback ladder).
+            db.prepare(`CREATE TABLE IF NOT EXISTS pending_quota_backoffs (
+          workspace_id TEXT PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+          target_at    TEXT NOT NULL,
+          resets_at    TEXT,
+          source       TEXT NOT NULL CHECK (source IN ('rate_limit_info', 'usage_api', 'fallback_ladder')),
+          retry_count  INTEGER NOT NULL DEFAULT 0,
+          created_at   TEXT NOT NULL
+        )`).run();
+        },
+    },
+    {
+        version: 20,
+        name: 'add-workspace-description',
+        migrate: (db) => {
+            // Free-form, optional summary of the mission shown in the sidebar and
+            // editable from the header. Nullable by design — pre-existing workspaces
+            // keep description = NULL until the user (or the brainstorm agent) sets
+            // one. Idempotent: skip the ALTER if the column is already present
+            // (covers re-runs and the case where a fresh-install ran initSchema first).
+            const cols = db.prepare('PRAGMA table_info(workspaces)').all();
+            if (cols.some((c) => c.name === 'description'))
+                return;
+            db.prepare('ALTER TABLE workspaces ADD COLUMN description TEXT').run();
+        },
+    },
+    {
+        version: 21,
+        name: 'add-workspace-agent-description',
+        migrate: (db) => {
+            // Agent-authored, optional summary of the mission written by the agent
+            // (typically at the end of brainstorm) via the renamed
+            // `set_workspace_agent_description` MCP tool. Distinct from the v20
+            // `description` column, which stays human-editable. Nullable, no default.
+            // Idempotent: skip the ALTER if the column already exists.
+            const cols = db.prepare('PRAGMA table_info(workspaces)').all();
+            if (cols.some((c) => c.name === 'agent_description'))
+                return;
+            db.prepare('ALTER TABLE workspaces ADD COLUMN agent_description TEXT').run();
+        },
+    },
 ];
 /** Current schema version — always equals the highest migration version. */
 export const SCHEMA_VERSION = migrations.length > 0 ? migrations[migrations.length - 1].version : 1;

package/dist/server/db/schema.js

@@ -27,6 +27,8 @@ export function initSchema(db) {
       no_progress_streak INTEGER NOT NULL DEFAULT 0,
       permission_profile TEXT NOT NULL DEFAULT 'bypass',
       agent_permission_mode TEXT NOT NULL DEFAULT 'bypass',
+      description TEXT,
+      agent_description TEXT,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL
     );
@@ -71,6 +73,15 @@ export function initSchema(db) {
       agent_session_id TEXT
     );
 
+    CREATE TABLE IF NOT EXISTS pending_quota_backoffs (
+      workspace_id TEXT PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+      target_at    TEXT NOT NULL,
+      resets_at    TEXT,
+      source       TEXT NOT NULL CHECK (source IN ('rate_limit_info', 'usage_api', 'fallback_ladder')),
+      retry_count  INTEGER NOT NULL DEFAULT 0,
+      created_at   TEXT NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS usage_snapshots (
       provider_id   TEXT PRIMARY KEY,
       status        TEXT NOT NULL,

package/dist/server/index.js

@@ -20,12 +20,13 @@ import settingsRouter from './routes/settings.js';
 import templatesRouter from './routes/templates.js';
 import usageRoutes from './routes/usage.js';
 import workspacesRouter from './routes/workspaces.js';
-import { getAvailableSkills, reconcileOrphanSessions, sendMessage, setBackendPort, startAgent, startWatchdog, stopAgent, stopWatchdog, } from './services/agent/orchestrator.js';
+import { getAvailableSkills, reconcileOrphanSessions, restoreRetryCountsFromDb, sendMessage, setBackendPort, startAgent, startWatchdog, stopAgent, stopWatchdog, } from './services/agent/orchestrator.js';
 import * as autoLoopService from './services/auto-loop-service.js';
 import { runContentMigrationIfNeeded } from './services/content-migration-service.js';
 import { createDailyDbBackupIfNeeded } from './services/db-backup-service.js';
 import { startDevServer, stopDevServer } from './services/dev-server-service.js';
 import { startPrWatcher, stopPrWatcher } from './services/pr-watcher-service.js';
+import * as quotaBackoffService from './services/quota-backoff-service.js';
 import { createTerminal, destroyAllTerminals, getTerminal } from './services/terminal-service.js';
 import { startUsagePoller, stopUsagePoller } from './services/usage/index.js';
 import * as wakeupService from './services/wakeup-service.js';
@@ -54,6 +55,11 @@ reconcileOrphanSessions();
 startWatchdog();
 wakeupService.rehydrate();
 autoLoopService.rehydrate();
+// Restore in-memory retry counts BEFORE re-arming the persisted backoff timers,
+// otherwise the next arm() after restart would compute the next ladder rung
+// from retryCount=0 and undo the progression.
+restoreRetryCountsFromDb();
+quotaBackoffService.restoreOnBoot((workspaceId) => autoLoopService.onQuotaBackoffExpired(workspaceId));
 startPrWatcher();
 startUsagePoller();
 // Create Hono app

package/dist/server/routes/workspaces.js

@@ -15,6 +15,7 @@ import { DEFAULT_NOTION_INITIAL_PROMPT, DEFAULT_SENTRY_INITIAL_PROMPT, renderNot
 import * as notionService from '../services/notion-service.js';
 import { renderPrTemplate } from '../services/pr-template-service.js';
 import { getAllPrStates } from '../services/pr-watcher-service.js';
+import * as quotaBackoffService from '../services/quota-backoff-service.js';
 import { DEFAULT_REVIEW_PROMPT_TEMPLATE, renderReviewTemplate } from '../services/review-template-service.js';
 import * as sentryService from '../services/sentry-service.js';
 import * as settingsService from '../services/settings-service.js';
@@ -585,6 +586,7 @@ app.post('/', migrationGuard, async (c) => {
             if (body.notionUrl) {
                 brainstormPrompt += `- get_notion_ticket() — retrieve the Notion ticket info (URL, ticket ID, extracted content)\n`;
             }
+            brainstormPrompt += `- kobo__set_workspace_agent_description(description) — keep the workspace's agent_description up to date as a short one-line summary of what you're currently doing or have just accomplished. The user sees this in the sidebar without opening the workspace. Update it whenever your focus shifts (e.g. "Investigating SERVICE-1600 → enriching local Notion file", then "Writing failing test for FacturX validator"). Plain text, max 200 chars. The current value is in kobo__get_workspace_info.\nThere is also a separate user-controlled \`description\` field on the workspace — DO NOT touch it. Only set_workspace_agent_description is yours to write; the user owns the other one.\n`;
             if (effectiveSettings.gitConventions) {
                 brainstormPrompt += `\n# Git conventions\nIMPORTANT: Before any git operation (commit, branch, rebase, merge, push), read and apply the conventions defined in \`.ai/.git-conventions.md\`. They are project-specific and override any default behavior. Re-read this file if you're unsure or if context was compacted.\n`;
             }
@@ -713,8 +715,16 @@ app.get('/pr-states', (c) => {
 app.get('/auto-loop-states', (c) => {
     try {
         const db = getDb();
+        // Task counts via LEFT JOIN so workspaces without tasks still appear with 0/0.
+        // Drives the sidebar AutoLoopChip badge (X / Y) for non-focused workspaces.
         const rows = db
-            .prepare('SELECT id, auto_loop, auto_loop_ready, no_progress_streak FROM workspaces WHERE archived_at IS NULL')
+            .prepare(`SELECT w.id, w.auto_loop, w.auto_loop_ready, w.no_progress_streak,
+                COUNT(t.id) AS tasks_total,
+                SUM(CASE WHEN t.status = 'done' THEN 1 ELSE 0 END) AS tasks_done
+         FROM workspaces w
+         LEFT JOIN tasks t ON t.workspace_id = w.id
+         WHERE w.archived_at IS NULL
+         GROUP BY w.id`)
             .all();
         const out = {};
         for (const r of rows) {
@@ -722,6 +732,8 @@ app.get('/auto-loop-states', (c) => {
                 auto_loop: r.auto_loop === 1,
                 auto_loop_ready: r.auto_loop_ready === 1,
                 no_progress_streak: r.no_progress_streak,
+                tasks_done: r.tasks_done ?? 0,
+                tasks_total: r.tasks_total ?? 0,
             };
         }
         return c.json(out);
@@ -808,6 +820,37 @@ app.delete('/:id/pending-wakeup', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// GET /api/workspaces/:id/quota-backoff — returns the pending quota backoff or null.
+app.get('/:id/quota-backoff', (c) => {
+    try {
+        const id = c.req.param('id');
+        const ws = workspaceService.getWorkspace(id);
+        if (!ws)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        const pending = quotaBackoffService.getPending(id);
+        c.header('Cache-Control', 'no-store');
+        return c.json(pending);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+// DELETE /api/workspaces/:id/quota-backoff — user-initiated cancel ("×" button).
+app.delete('/:id/quota-backoff', (c) => {
+    try {
+        const id = c.req.param('id');
+        const ws = workspaceService.getWorkspace(id);
+        if (!ws)
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        quotaBackoffService.cancel(id, 'user');
+        return new Response(null, { status: 204 });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // POST /api/workspaces/:id/pending-wakeup — agent-initiated schedule via the
 // `kobo__schedule_wakeup` MCP tool. Replaces any existing pending wakeup.
 app.post('/:id/pending-wakeup', async (c) => {
@@ -1057,6 +1100,28 @@ app.post('/:id/tasks/notify-updated', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// POST /api/workspaces/:id/agent-description/notify-updated — broadcast
+// workspace:agent-description-updated after the MCP set_workspace_agent_description
+// handler wrote the column directly. Mirrors the notify-done / notify-updated
+// pattern: the route doesn't re-write, just emits the WS event so the sidebar
+// chip + workspace header italic line refresh in real time.
+app.post('/:id/agent-description/notify-updated', (c) => {
+    try {
+        const id = c.req.param('id');
+        const workspace = workspaceService.getWorkspace(id);
+        if (!workspace) {
+            return c.json({ error: `Workspace '${id}' not found` }, 404);
+        }
+        wsService.emitEphemeral(id, 'workspace:agent-description-updated', {
+            agentDescription: workspace.agentDescription,
+        });
+        return new Response(null, { status: 204 });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 // POST /api/workspaces/:id/tasks/:taskId/notify-done — broadcast task:updated event
 app.post('/:id/tasks/:taskId/notify-done', (c) => {
     try {
@@ -1270,6 +1335,10 @@ app.patch('/:id', migrationGuard, async (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
+        // agent_description is exclusively writable via the MCP tool, never via the API.
+        if ('agent_description' in body) {
+            return c.json({ error: 'agent_description must be set via the agent MCP tool, not via the API' }, 400);
+        }
         let updated = workspace;
         if (body.model !== undefined) {
             updated = workspaceService.updateWorkspaceModel(id, body.model);
@@ -1289,12 +1358,20 @@ app.patch('/:id', migrationGuard, async (c) => {
         if (body.name !== undefined) {
             updated = workspaceService.updateWorkspaceName(id, body.name);
         }
+        if ('description' in body) {
+            const desc = body.description;
+            if (desc !== null && typeof desc !== 'string') {
+                return c.json({ error: 'description must be a string or null' }, 400);
+            }
+            updated = workspaceService.updateWorkspaceDescription(id, desc);
+        }
         if (!body.status &&
             body.model === undefined &&
             body.reasoningEffort === undefined &&
             body.agentPermissionMode === undefined &&
-            body.name === undefined) {
-            return c.json({ error: 'Missing field: status, model, reasoningEffort, agentPermissionMode, or name' }, 400);
+            body.name === undefined &&
+            !('description' in body)) {
+            return c.json({ error: 'Missing field: status, model, reasoningEffort, agentPermissionMode, name, or description' }, 400);
         }
         return c.json(updated);
     }
@@ -1305,7 +1382,8 @@ app.patch('/:id', migrationGuard, async (c) => {
         }
         if (message.includes('Invalid status transition') ||
             message.includes('name cannot be empty') ||
-            message.includes('name cannot exceed')) {
+            message.includes('name cannot exceed') ||
+            message.includes('Description must be')) {
             return c.json({ error: message }, 400);
         }
         return c.json({ error: message }, 500);
@@ -1619,7 +1697,7 @@ app.get('/:id/git-stats', async (c) => {
         const behindCount = gitOps.getCommitsBehind(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const diffStats = gitOps.getStructuredDiffStatsBetween(worktreePath, workspace.sourceBranch, workspace.workingBranch);
         const pr = await gitOps.getPrStatusAsync(workspace.projectPath, workspace.workingBranch);
-        const unpushedCount = await gitOps.getUnpushedCountAsync(worktreePath);
+        const unpushedCount = await gitOps.getUnpushedCountAsync(worktreePath, workspace.workingBranch);
         const workingTree = gitOps.getWorkingTreeStatus(worktreePath);
         return c.json({
             commitCount,

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

@@ -101,7 +101,10 @@ export function createClaudeCodeEngine() {
                     if (lower.includes('rate limit exceeded') ||
                         lower.includes('rate_limit_exceeded') ||
                         (lower.includes('429') && lower.includes('rate')) ||
-                        lower.includes('quota exceeded')) {
+                        lower.includes('quota exceeded') ||
+                        lower.includes('out of extra usage') ||
+                        // "Claude AI usage limit reached" — Anthropic's 5h/4h cap message
+                        lower.includes('usage limit')) {
                         onEvent({ kind: 'error', category: 'quota', message: data });
                     }
                     else if (lower.includes('no conversation found with session id')) {

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

@@ -56,7 +56,7 @@ export function createMapperState() {
     return { sessionStartedEmitted: false, openMessages: new Map(), sawErrorResult: false };
 }
 /** Known SDK `result` subtypes that indicate the run failed. */
-const KNOWN_ERROR_RESULT_SUBTYPES = new Set(['error_max_turns', 'error_during_execution']);
+export const KNOWN_ERROR_RESULT_SUBTYPES = new Set(['error_max_turns', 'error_during_execution']);
 function isErrorResultSubtype(subtype) {
     if (!subtype)
         return false;
@@ -211,8 +211,12 @@ export function mapSdkMessage(msg, state) {
         if (isErrorResultSubtype(subtype)) {
             state.sawErrorResult = true;
             const detail = (typeof parsed.error === 'string' && parsed.error) || (typeof parsed.result === 'string' && parsed.result) || '';
+            // "Claude AI usage limit reached" is Anthropic's 5h/4h cap surface — added
+            // to the regex so the orchestrator transitions the workspace to `quota`
+            // (not `error`) and the auto-loop backoff path engages.
+            const isQuota = /out of extra usage|rate limit|usage limit/i.test(detail);
             const message = detail ? `Agent run failed (${subtype}): ${detail}` : `Agent run failed (${subtype})`;
-            events.push({ kind: 'error', category: 'other', message });
+            events.push({ kind: 'error', category: isQuota ? 'quota' : 'other', message });
         }
         const usage = parsed.usage;
         if (usage) {