@loicngr/kobo 1.7.4 → 1.7.6

package/README.md

@@ -31,10 +31,13 @@ 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
-- **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
+- **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. Delay is clamped to `[60s, 6h]`. The kobo-tasks MCP server also exposes `kobo__schedule_wakeup` / `kobo__cancel_wakeup` for the same flow with first-class tool descriptors
+- **Recurring & one-shot crons** — agents schedule recurring triggers via `kobo__cron_create(expression, prompt, label?, mode?, oneShot?)`. Standard 5-field cron expressions (`*/30 * * * *`) plus helpers (`@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`). Two modes: `'resume'` (default) pins the cron to the session that scheduled it so each fire continues that conversation; `'fresh'` spawns a brand-new session per fire (clean context, ideal for periodic CI / dashboard checks). `oneShot: true` cancels the cron after the first real fire — useful for "trigger once at a specific date/time" without recurring. Crons are persisted in SQLite, re-armed on restart with skip-missed semantics (no catchup spam after downtime), and skip-if-active when a session is already running. Multiple crons per workspace. The native Claude Code `CronCreate` tool is also intercepted and mirrored as a kobo cron so even agents using the SDK-default tool benefit from persistence
+- **Schedule panel in the right drawer** — dedicated tab listing every wakeup and cron currently armed for the focused workspace, with their next/last fire times, prompt preview, and a `×` button to cancel inline. Sidebar workspace cards display an `event_repeat` icon when one or more crons are scheduled, even for workspaces not currently focused — broadcast live via WebSocket events
 
 ## Tech stack
 
@@ -101,8 +104,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 +232,9 @@ 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)
+│   │   ├── cron-service.ts                 # persisted cron schedules (recurring + one-shot, resume/fresh modes)
+│   │   ├── wakeup-service.ts               # persisted one-shot session resumes (clamped to [60s, 6h])
 │   │   └── …                               # 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 +258,29 @@ 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 |
+| `pending_crons` | one row per scheduled cron — expression, prompt, label, optional pinned `agent_session_id` (= resume mode) or NULL (= fresh mode), `next_fire_at`, `last_fired_at`, `one_shot` flag, re-armed on server restart with skip-missed semantics |
 
 ## 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`, `cron_create`, `cron_delete`, `cron_list`, `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. Tools that arm in-memory timers (`cron_create`, `cron_delete`) route through the backend HTTP API instead — the timer Map lives in the backend process which owns the orchestrator, so the cron survives the MCP server's session-bound lifetime.
 
 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

@@ -1,6 +1,7 @@
 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 { slugifyProjectName } from '../server/utils/project-slug.js';
 import { resolveWorkspaceWorktreePath } from '../server/utils/worktree-paths.js';
@@ -37,6 +38,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 +179,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 +200,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,
@@ -354,3 +380,17 @@ export function getSessionUsageHandler(db, workspaceId) {
         currentSession: { sessionId: currentSessionId, ...current },
     };
 }
+// ── Crons ────────────────────────────────────────────────────────────────────
+/**
+ * List every cron currently armed for a workspace.
+ *
+ * Note: cron_create and cron_delete are NOT exposed as handlers — they route
+ * through the backend HTTP API (`POST/DELETE /api/workspaces/:id/crons`)
+ * because their `setTimeout` must live in the backend process (which owns
+ * the orchestrator). Handlers here would arm timers in the MCP sub-process,
+ * which dies with the agent session, and fires would never reach a real
+ * session resume. The list handler is a pure read so it's safe to keep local.
+ */
+export function cronListHandler(_db, workspaceId) {
+    return { ok: true, crons: cronService.listForWorkspace(workspaceId) };
+}

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

@@ -4,8 +4,9 @@ import path from 'node:path';
 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 { getDb } from '../server/db/index.js';
+import { runMigrations } from '../server/db/migrations.js';
+import { createTaskHandler, cronListHandler, 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;
@@ -20,10 +21,21 @@ if (!dbPath) {
 }
 let db;
 try {
-    db = new Database(dbPath, { readonly: false });
-    db.pragma('journal_mode = WAL');
-    db.pragma('busy_timeout = 5000');
-    db.pragma('foreign_keys = ON');
+    // Use the shared `getDb` singleton so any service that calls `getDb()`
+    // internally (e.g. cron-service.arm) hits the SAME connection as this
+    // MCP server, against the SAME DB file. Without this bootstrap, the
+    // singleton would resolve via getDbPath() → getKoboHome() → KOBO_HOME
+    // env var, which the agent SDK does NOT pass to the MCP server (only
+    // KOBO_DB_PATH is passed). That would silently open a second connection
+    // against the user's prod DB at ~/.config/kobo/kobo.db, which may not
+    // even have the same schema as the dev DB the backend is using.
+    db = getDb(dbPath);
+    // Defensive: run migrations to ensure the schema is at the latest version.
+    // The backend already ran them at boot, but this MCP server might be the
+    // first to touch the DB (e.g. tests, race at first boot, or KOBO_DB_PATH
+    // pointing somewhere the backend hasn't migrated). Idempotent — no-op if
+    // the DB is already at SCHEMA_VERSION.
+    runMigrations(db);
 }
 catch (err) {
     console.error('[kobo-tasks-server] Failed to open database:', err);
@@ -68,6 +80,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 +188,67 @@ 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: 'cron_create',
+            description: 'Schedule a recurring trigger on THIS workspace. At each fire, Kōbō waits for the workspace to be idle (no active session) and then resumes the same conversation by injecting `prompt` as the next user message — same UX as `schedule_wakeup` but recurring. Skip-if-active: if a session is already running when the timer fires, that occurrence is skipped, the next occurrence is computed, and the cron continues. The cron persists across server restarts (skip-missed semantics on boot — no catchup spam). Delete with `cron_delete(id)`. Multiple crons per workspace are allowed.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    expression: {
+                        type: 'string',
+                        description: 'Standard 5-field cron expression (`min hour dom month dow`) or one of the helpers `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`. Example: `*/30 * * * *` = every 30 minutes; `0 9 * * 1` = every Monday at 9am. Validated at create time.',
+                    },
+                    prompt: {
+                        type: 'string',
+                        description: 'The prompt to inject as the next user message at each fire.',
+                    },
+                    label: {
+                        type: 'string',
+                        description: 'Optional human-readable label for the cron (shown in the UI).',
+                    },
+                    mode: {
+                        type: 'string',
+                        enum: ['resume', 'fresh'],
+                        description: "How each fire is handled. 'resume' (default) pins the cron to the session you're calling from, so every fire continues THAT conversation by injecting `prompt` as the next user message — use this when the cron should follow up on ongoing work. 'fresh' starts a brand-new session at every fire with a clean context — use this for periodic checks (e.g. CI watch, daily standup) that don't need conversation continuity.",
+                    },
+                    oneShot: {
+                        type: 'boolean',
+                        description: "When true, the cron cancels itself after the first real fire (default false = recurring). Use this to schedule a single trigger at a specific cron-expressible time (e.g. `0 14 7 6 *` = next 7 June at 14:00) without it repeating yearly. Skip-active fires don't consume the one-shot — the cron retries at the next occurrence until it actually runs once.",
+                    },
+                },
+                required: ['expression', 'prompt'],
+            },
+        },
+        {
+            name: 'cron_delete',
+            description: "Cancel a previously-armed cron by id. Idempotent — returns ok=true even if the id is unknown. Only the workspace's own crons can be cancelled (cron_list to see them).",
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'The cron id returned by cron_create.' },
+                },
+                required: ['id'],
+            },
+        },
+        {
+            name: 'cron_list',
+            description: 'List all crons currently armed on THIS workspace, including their next and last fire times.',
+            inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        },
         {
             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.',
@@ -294,13 +383,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'schedule_wakeup',
-            description: 'CALL to schedule a follow-up turn on THIS workspace after a delay. End the current turn normally; once it finishes and the workspace is idle, Kōbō waits `delaySeconds`, then resumes the same conversation by injecting `prompt` as the next user message. The wakeup is scoped to the current workspace and resumes its latest session — you cannot target another workspace or another session. If a turn is still active when the timer fires, the wakeup is skipped (status: `session-active`). Replaces any previously pending wakeup on this workspace. Delay is clamped to [60, 3600] seconds. Prefer this over the built-in `ScheduleWakeup` tool — it is the SDK-supported entry point.',
+            description: 'CALL to schedule a follow-up turn on THIS workspace after a delay. End the current turn normally; once it finishes and the workspace is idle, Kōbō waits `delaySeconds`, then resumes the same conversation by injecting `prompt` as the next user message. The wakeup is scoped to the current workspace and resumes its latest session — you cannot target another workspace or another session. If a turn is still active when the timer fires, the wakeup is skipped (status: `session-active`). Replaces any previously pending wakeup on this workspace. Delay is clamped to [60, 21600] seconds (1min to 6h). Prefer this over the built-in `ScheduleWakeup` tool — it is the SDK-supported entry point.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     delaySeconds: {
                         type: 'number',
-                        description: 'Seconds from now until the wakeup fires. Clamped to [60, 3600].',
+                        description: 'Seconds from now until the wakeup fires. Clamped to [60, 21600] (1min to 6h).',
                     },
                     prompt: {
                         type: 'string',
@@ -396,6 +485,66 @@ 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 === 'cron_create') {
+            const expression = a.expression;
+            const prompt = a.prompt;
+            const label = typeof a.label === 'string' ? a.label : undefined;
+            const mode = typeof a.mode === 'string' ? a.mode : undefined;
+            const oneShot = typeof a.oneShot === 'boolean' ? a.oneShot : undefined;
+            if (typeof expression !== 'string' || typeof prompt !== 'string') {
+                return fail('expression and prompt parameters are required');
+            }
+            if (mode !== undefined && mode !== 'resume' && mode !== 'fresh') {
+                return fail("mode must be 'resume' or 'fresh'");
+            }
+            // Route through the backend so the in-memory `setTimeout` lives in the
+            // backend process (which owns orchestrator + WS broadcast). Calling
+            // cron-service.arm() directly here would persist the row but arm the
+            // timer in the MCP server sub-process, which dies with the agent
+            // session — fires would never trigger a real session resume.
+            try {
+                const created = (await backendRequest('POST', `/api/workspaces/${workspaceId}/crons`, {
+                    expression,
+                    prompt,
+                    label,
+                    mode,
+                    oneShot,
+                }));
+                return ok({ ok: true, cron: created.cron });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return ok({ ok: false, error: message });
+            }
+        }
+        if (name === 'cron_delete') {
+            const id = a.id;
+            if (typeof id !== 'string')
+                return fail('id parameter is required');
+            // Same reason as cron_create — the backend owns the timer Map.
+            try {
+                await backendRequest('DELETE', `/api/workspaces/${workspaceId}/crons/${id}`);
+                return ok({ ok: true });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return ok({ ok: false, error: message });
+            }
+        }
+        if (name === 'cron_list') {
+            const result = cronListHandler(db, workspaceId);
+            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,93 @@ 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();
+        },
+    },
+    {
+        version: 22,
+        name: 'add-pending-crons',
+        migrate: (db) => {
+            // Per-workspace cron schedules: each row arms a recurring agent prompt
+            // on a cron expression. Sibling timer table to pending_wakeups /
+            // pending_quota_backoffs. Many rows per workspace (unlike the one-row
+            // sibling tables), so id is the primary key. CASCADE on workspace
+            // delete to keep the timer set tidy. Idempotent via IF NOT EXISTS.
+            db.prepare(`CREATE TABLE IF NOT EXISTS pending_crons (
+          id                TEXT PRIMARY KEY,
+          workspace_id      TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+          expression        TEXT NOT NULL,
+          prompt            TEXT NOT NULL,
+          label             TEXT,
+          agent_session_id  TEXT,
+          next_fire_at      TEXT NOT NULL,
+          last_fired_at     TEXT,
+          created_at        TEXT NOT NULL
+        )`).run();
+            db.prepare('CREATE INDEX IF NOT EXISTS idx_pending_crons_workspace ON pending_crons(workspace_id)').run();
+            db.prepare('CREATE INDEX IF NOT EXISTS idx_pending_crons_next_fire ON pending_crons(next_fire_at)').run();
+        },
+    },
+    {
+        version: 23,
+        name: 'add-pending-crons-one-shot',
+        migrate: (db) => {
+            // One-shot cron: fires once and cancels itself. Distinct from a wakeup
+            // because it still uses cron expressions (can target an absolute date,
+            // e.g. `0 14 7 6 *` = "next 7 June at 14:00") rather than a delay.
+            // Default 0 (recurring) preserves existing behaviour.
+            const cols = db.prepare('PRAGMA table_info(pending_crons)').all();
+            if (!cols.some((c) => c.name === 'one_shot')) {
+                db.prepare('ALTER TABLE pending_crons ADD COLUMN one_shot INTEGER NOT NULL DEFAULT 0').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,31 @@ 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 pending_crons (
+      id                TEXT PRIMARY KEY,
+      workspace_id      TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      expression        TEXT NOT NULL,
+      prompt            TEXT NOT NULL,
+      label             TEXT,
+      agent_session_id  TEXT,
+      next_fire_at      TEXT NOT NULL,
+      last_fired_at     TEXT,
+      one_shot          INTEGER NOT NULL DEFAULT 0,
+      created_at        TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_pending_crons_workspace ON pending_crons(workspace_id);
+    CREATE INDEX IF NOT EXISTS idx_pending_crons_next_fire ON pending_crons(next_fire_at);
+
     CREATE TABLE IF NOT EXISTS usage_snapshots (
       provider_id   TEXT PRIMARY KEY,
       status        TEXT NOT NULL,

package/dist/server/index.js

@@ -20,12 +20,14 @@ 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 * as cronService from './services/cron-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 +56,12 @@ 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));
+cronService.restoreOnBoot();
 startPrWatcher();
 startUsagePoller();
 // Create Hono app

package/dist/server/routes/health.js

@@ -63,15 +63,73 @@ app.get('/report', (c) => {
             worktreesMissing.push({ workspaceId: ws.id, name: ws.name, path: wtPath, exists: false });
         }
     }
-    // Orphan agent sessions — marked running but PID no longer alive
+    // Orphan agent sessions — marked running but PID no longer alive.
+    // Also collect the alive ones for the active-state panel.
     const runningSessions = db
-        .prepare("SELECT pid FROM agent_sessions WHERE status = 'running' AND pid IS NOT NULL")
+        .prepare(`
+      SELECT s.pid AS pid, s.workspace_id AS workspaceId, s.started_at AS startedAt, w.name AS workspaceName
+      FROM agent_sessions s
+      JOIN workspaces w ON w.id = s.workspace_id
+      WHERE s.status = 'running' AND s.pid IS NOT NULL
+    `)
         .all();
     let orphaned = 0;
+    const agentSessionsAlive = [];
     for (const s of runningSessions) {
-        if (s.pid && !isProcessAlive(s.pid))
+        if (!s.pid)
+            continue;
+        if (isProcessAlive(s.pid)) {
+            agentSessionsAlive.push({
+                workspaceId: s.workspaceId,
+                workspaceName: s.workspaceName,
+                pid: s.pid,
+                startedAt: s.startedAt,
+            });
+        }
+        else {
             orphaned++;
+        }
     }
+    // Active state — features the user wants to see at a glance:
+    // pending quota backoffs, scheduled wakeups, armed auto-loops, running dev servers.
+    const quotaBackoffs = db
+        .prepare(`
+      SELECT q.workspace_id AS workspaceId, w.name AS name, q.target_at AS targetAt,
+             q.resets_at AS resetsAt, q.source AS source, q.retry_count AS retryCount
+      FROM pending_quota_backoffs q
+      JOIN workspaces w ON w.id = q.workspace_id
+      ORDER BY q.target_at ASC
+    `)
+        .all();
+    const pendingWakeups = db
+        .prepare(`
+      SELECT p.workspace_id AS workspaceId, w.name AS name, p.target_at AS targetAt, p.reason AS reason
+      FROM pending_wakeups p
+      JOIN workspaces w ON w.id = p.workspace_id
+      ORDER BY p.target_at ASC
+    `)
+        .all();
+    const autoLoopActiveRaw = db
+        .prepare(`
+      SELECT id AS workspaceId, name, auto_loop_ready AS ready
+      FROM workspaces
+      WHERE auto_loop = 1 AND archived_at IS NULL
+      ORDER BY name ASC
+    `)
+        .all();
+    const autoLoopActive = autoLoopActiveRaw.map((r) => ({
+        workspaceId: r.workspaceId,
+        name: r.name,
+        ready: r.ready === 1,
+    }));
+    const devServersRunning = db
+        .prepare(`
+      SELECT id AS workspaceId, name
+      FROM workspaces
+      WHERE dev_server_status = 'running' AND archived_at IS NULL
+      ORDER BY name ASC
+    `)
+        .all();
     const settingsRow = db.prepare('SELECT COUNT(*) as n FROM workspaces').get();
     const archivedRow = db.prepare('SELECT COUNT(*) as n FROM workspaces WHERE archived_at IS NOT NULL').get();
     const report = {
@@ -95,6 +153,13 @@ app.get('/report', (c) => {
             sentry: { configured: Boolean(healthGlobalSettings.sentryMcpKey) },
             editor: { configured: Boolean(healthGlobalSettings.editorCommand) },
         },
+        active: {
+            quotaBackoffs,
+            pendingWakeups,
+            autoLoopActive,
+            agentSessionsAlive,
+            devServersRunning,
+        },
     };
     return c.json(report);
 });