@loicngr/kobo 1.6.12 → 1.6.14

package/README.md

@@ -17,8 +17,8 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Task & acceptance criteria tracking** — the agent reports progress through a dedicated MCP server (`kobo-tasks`) that reads and updates tasks directly from the SQLite database
 - **Documents panel** — tree view in the right drawer that surfaces every AI-generated markdown file under `docs/plans/`, `docs/superpowers/`, and `.ai/thoughts/`. Paths mentioned in chat messages are auto-detected against the catalogue and become one-click deep-links into the panel
 - **Git panel with inline diff viewer** — Monaco-powered side-by-side / inline diff of the working branch against its source, with file tree (same q-tree as Documents), inline rebase/merge conflict resolution, and a clean action bar: `Sync` split-button (pull / rebase / merge), `Push`, `Diff`, `Create PR`
-- **Notion integration** — pull workspace missions straight from Notion pages, extract markdown, and use it as the source of truth for acceptance criteria
-- **Sentry integration** — paste a Sentry issue URL to spin up a dedicated "fix workspace" with the stacktrace, tags, and offending spans written to `.ai/thoughts/SENTRY-<id>.md`; the agent is primed with a TDD fix workflow and has access to the Sentry MCP tools for deeper digging
+- **Notion integration** — pull workspace missions straight from Notion pages, extract markdown, and use it as the source of truth for acceptance criteria. Right-click a Notion-sourced workspace to jump back to its source page in one click
+- **Sentry integration** — paste a Sentry issue URL to spin up a dedicated "fix workspace" with the stacktrace, tags, and offending spans written to `.ai/thoughts/SENTRY-<id>.md`; the agent is primed with a TDD fix workflow and has access to the Sentry MCP tools for deeper digging. Right-click reopens the Sentry issue in Sentry's UI
 - **Per-workspace dev servers** — start/stop Docker or Node dev servers scoped to each branch, with log streaming
 - **Conventional-commit enforcement** — project-level git conventions are written to `.ai/.git-conventions.md` inside every workspace so Claude follows them during commits
 - **Pull request automation** — one-click `push`, `pull`, `open-pr`, and "change PR base" endpoints integrate with the GitHub CLI, using a configurable prompt template
@@ -26,11 +26,12 @@ Think of it as an apprentice's hall: you hand out missions, each apprentice sets
 - **Prompt templates** — personal library of reusable prompts with variable substitution (`{working_branch}`, `{commit_count}`, etc.), insertable from the chat input via `/` autocomplete; editable in Settings > Templates
 - **Favorites and tags** — pin workspaces to the top via right-click favourite, organise with per-workspace tags filterable from the sidebar; a global tag catalogue keeps colours consistent across workspaces
 - **Health panel + config export/import** — inspect backend health (agent sessions, migration state, dev servers, DB size) and roundtrip your Kōbō config (settings, templates, skills) between machines via JSON
-- **Usage tracking** — rolling input/output token counts and cost estimates per workspace, aggregated across sessions and live-updated from `usage` events
+- **Account-level quota panel** — a colored mini-bar badge in the chat footer shows the current Claude Code 5-hour and 7-day usage, fed by a backend service that polls Anthropic's OAuth usage endpoint every 60 seconds. Click to open a popover with full bars, reset times, a "Refresh now" button, and a one-click jump to the Stats tab. Pluggable per-provider (Codex-ready), persisted in SQLite so the badge is populated on cold start, and account-level so it's the same across workspaces sharing the same engine
 - **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
+- **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
+- **Attach existing worktrees** — Kōbō detects orphan worktrees under `.worktrees/` (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
 
@@ -99,7 +100,7 @@ npm start           # runs the compiled server
 ### Test & lint
 
 ```bash
-npm test            # backend vitest suite (740+ tests)
+npm test            # backend vitest suite (950+ tests)
 npm run test:client # client vitest suite (Pinia stores + pure utils, 85+ tests)
 npm run test:all    # backend + client suites
 npm run lint        # biome check (lint + format verification)
@@ -226,8 +227,9 @@ src/
 │   │   │   ├── event-router.ts             # maps engine AgentEvent stream to WS emit + DB side-effects
 │   │   │   └── 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
 │   │   └── …                               # workspace, dev-server, ws, notion, sentry, settings, pr-template
-│   ├── routes/                             # Hono handlers (workspaces, engines, migration, templates, …)
+│   ├── routes/                             # Hono handlers (workspaces, engines, migration, templates, usage, …)
 │   └── utils/                              # git-ops, process-tracker, paths
 ├── shared/                                 # modules shared by backend and frontend (e.g. model catalogue)
 ├── client/                                 # Vue 3 + Quasar SPA
@@ -253,6 +255,7 @@ See [`AGENTS.md`](./AGENTS.md) for a deeper dive into conventions, data model, W
 | `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 |
 
 ## MCP server
 
@@ -271,6 +274,8 @@ Kōbō reads settings from `~/.config/kobo/settings.json` (or falls back to defa
 - `prPromptTemplate` — template rendered when opening a PR via the `/open-pr` endpoint; supports `{{pr_number}}`, `{{pr_url}}`, `{{branch_name}}`, `{{diff_stats}}`, `{{commits}}`, etc.
 - `gitConventions` — markdown-formatted git conventions written to `.ai/.git-conventions.md` in every workspace so the agent follows them when committing
 - `devServer` — per-project `startCommand` / `stopCommand` for launching workspace-scoped dev servers
+- `e2e` — per-project E2E test framework (`cypress`, `playwright`, `jest`, `vitest`, `other`, or none) plus an optional skill name and prompt; consumed by the auto-loop grooming step to inject `[E2E] ` test sub-tasks alongside parent tasks
+- `finalization` — per-project free-form prompt that runs as the very last auto-loop iteration. The grooming step injects a `[FINAL]`-prefixed task at the end of the list whose iteration block is replaced by this prompt. Default content asks the agent to run linters, type-checkers, and tests. Empty string disables the feature.
 
 ## Contributing
 

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

@@ -152,7 +152,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, 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, 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`);
@@ -163,7 +163,7 @@ export function getWorkspaceInfoHandler(db, workspaceId) {
         projectPath: row.project_path,
         sourceBranch: row.source_branch,
         workingBranch: row.working_branch,
-        worktreePath: path.join(row.project_path, '.worktrees', row.working_branch),
+        worktreePath: row.worktree_path ?? path.join(row.project_path, '.worktrees', row.working_branch),
         status: row.status,
         model: row.model,
         notionUrl: row.notion_url,

package/dist/server/db/migrations.js

@@ -130,6 +130,30 @@ export const migrations = [
             db.prepare('ALTER TABLE workspaces ADD COLUMN sentry_url TEXT').run();
         },
     },
+    {
+        version: 15,
+        name: 'add-workspace-worktree-path',
+        migrate: (db) => {
+            db.transaction(() => {
+                db.prepare('ALTER TABLE workspaces ADD COLUMN worktree_path TEXT').run();
+                db.prepare('ALTER TABLE workspaces ADD COLUMN worktree_owned INTEGER NOT NULL DEFAULT 1').run();
+                db.prepare("UPDATE workspaces SET worktree_path = project_path || '/.worktrees/' || working_branch WHERE worktree_path IS NULL").run();
+            })();
+        },
+    },
+    {
+        version: 16,
+        name: 'add-usage-snapshots-table',
+        migrate: (db) => {
+            db.prepare(`CREATE TABLE IF NOT EXISTS usage_snapshots (
+          provider_id   TEXT PRIMARY KEY,
+          status        TEXT NOT NULL,
+          error_message TEXT,
+          buckets_json  TEXT NOT NULL,
+          fetched_at    TEXT NOT NULL
+        )`).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

@@ -11,6 +11,8 @@ export function initSchema(db) {
       notion_url TEXT,
       notion_page_id TEXT,
       sentry_url TEXT,
+      worktree_path TEXT,
+      worktree_owned INTEGER NOT NULL DEFAULT 1,
       model TEXT NOT NULL DEFAULT 'claude-opus-4-7',
       reasoning_effort TEXT NOT NULL DEFAULT 'auto',
       permission_mode TEXT NOT NULL DEFAULT 'auto-accept',
@@ -67,6 +69,14 @@ export function initSchema(db) {
       created_at   TEXT NOT NULL
     );
 
+    CREATE TABLE IF NOT EXISTS usage_snapshots (
+      provider_id   TEXT PRIMARY KEY,
+      status        TEXT NOT NULL,
+      error_message TEXT,
+      buckets_json  TEXT NOT NULL,
+      fetched_at    TEXT NOT NULL
+    );
+
     CREATE INDEX IF NOT EXISTS idx_tasks_workspace_id ON tasks(workspace_id);
     CREATE INDEX IF NOT EXISTS idx_agent_sessions_workspace_id ON agent_sessions(workspace_id);
     CREATE INDEX IF NOT EXISTS idx_ws_events_workspace_id ON ws_events(workspace_id);

package/dist/server/index.js

@@ -19,6 +19,7 @@ import searchRouter from './routes/search.js';
 import sentryRouter from './routes/sentry.js';
 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 * as autoLoopService from './services/auto-loop-service.js';
@@ -27,8 +28,9 @@ 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 { createTerminal, destroyAllTerminals, getTerminal } from './services/terminal-service.js';
+import { startUsagePoller, stopUsagePoller } from './services/usage/index.js';
 import * as wakeupService from './services/wakeup-service.js';
-import { emit, handleConnection, setMessageHandler } from './services/websocket-service.js';
+import { emit, emitEphemeral, handleConnection, setMessageHandler } from './services/websocket-service.js';
 import { getActiveSession, getWorkspace, updateWorkspaceStatus } from './services/workspace-service.js';
 import { getClientSpaPath, getDbPath, getKoboHome, getPackageVersion } from './utils/paths.js';
 import { initProcessCleanup, killAll as killAllTrackedProcesses } from './utils/process-tracker.js';
@@ -62,6 +64,7 @@ startWatchdog();
 wakeupService.rehydrate();
 autoLoopService.rehydrate();
 startPrWatcher();
+startUsagePoller();
 // Create Hono app
 const app = new Hono();
 // Health check (root / is handled by the SPA catch-all below)
@@ -75,6 +78,7 @@ app.route('/api/git', gitRouter);
 app.route('/api/settings', settingsRouter);
 app.route('/api/dev-server', devServerRouter);
 app.route('/api/templates', templatesRouter);
+app.route('/api/usage', usageRoutes);
 app.route('/api/workspaces', documentsRouter);
 app.route('/api/search', searchRouter);
 app.route('/api/health', healthRouter);
@@ -200,7 +204,7 @@ terminalWss.on('connection', (ws, workspaceId) => {
                     ws.send(JSON.stringify({ type: 'error', message: 'Workspace is archived' }));
                     return;
                 }
-                const cwd = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+                const cwd = workspace.worktreePath;
                 try {
                     currentPty = createTerminal(workspaceId, cwd);
                 }
@@ -233,6 +237,19 @@ terminalWss.on('connection', (ws, workspaceId) => {
 setMessageHandler((type, payload) => {
     const p = payload;
     if (type === 'chat:message' && p?.workspaceId && p?.content) {
+        // Auto-loop owns the agent's turns — a stray user message would land in
+        // the middle of an iteration (or in a freshly spawned next one) and break
+        // the deterministic loop contract. Reject server-side so direct WS clients
+        // can't bypass the frontend's input lock. Grooming phase (ready=0) is
+        // skipped — the user must stay free to answer the agent's questions.
+        const autoLoopStatus = autoLoopService.getStatus(p.workspaceId);
+        if (autoLoopStatus.auto_loop && autoLoopStatus.auto_loop_ready) {
+            emitEphemeral(p.workspaceId, 'chat:rejected', {
+                reason: 'auto-loop-active',
+                message: 'Auto-loop is running — disable it before sending a message',
+            });
+            return;
+        }
         // Prefer the session explicitly selected by the client (sessionId hint),
         // falling back to the running/most-recent non-idle session so idle sessions
         // never steal the tagging.
@@ -257,7 +274,7 @@ setMessageHandler((type, payload) => {
             try {
                 const workspace = getWorkspace(p.workspaceId);
                 if (workspace) {
-                    const worktreePath = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+                    const worktreePath = workspace.worktreePath;
                     // Plan mode blocks MCP tools — when the caller knows the message
                     // requires them (e.g. grooming), it sets the override to bypass the
                     // workspace default for this spawn only.
@@ -278,7 +295,7 @@ setMessageHandler((type, payload) => {
                 console.error(`[ws] workspace:start — workspace '${p.workspaceId}' not found`);
                 return;
             }
-            const worktreePath = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+            const worktreePath = workspace.worktreePath;
             const prompt = p.prompt ?? 'Continue the previous task where you left off.';
             startAgent(p.workspaceId, worktreePath, prompt, workspace.model, false, workspace.permissionMode, undefined, workspace.reasoningEffort);
         }
@@ -368,6 +385,12 @@ function gracefulShutdown(signal) {
     catch {
         // Best-effort
     }
+    try {
+        stopUsagePoller();
+    }
+    catch {
+        // Best-effort
+    }
     // Kill all tracked child processes (agents, dev servers)
     try {
         killAllTrackedProcesses();

package/dist/server/routes/documents.js

@@ -59,7 +59,7 @@ app.get('/:id/documents', (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         const documents = [];
         for (const dir of DOCUMENT_DIRS) {
             const absDir = path.join(worktreePath, dir);
@@ -97,7 +97,7 @@ app.get('/:id/document', (c) => {
         if (!normalized.endsWith(MD_EXT)) {
             return c.json({ error: 'Only .md files can be read' }, 400);
         }
-        const worktreePath = path.join(workspace.projectPath, '.worktrees', workspace.workingBranch);
+        const worktreePath = workspace.worktreePath;
         const absPath = path.join(worktreePath, normalized);
         if (!existsSync(absPath)) {
             return c.json({ error: `Document not found: ${normalized}` }, 404);

package/dist/server/routes/git.js

@@ -1,4 +1,6 @@
 import { Hono } from 'hono';
+import { getDb } from '../db/index.js';
+import { listOrphanWorktrees } from '../services/worktree-service.js';
 import { listBranches, listRemoteBranches } from '../utils/git-ops.js';
 /** Hono sub-router for git-related endpoints (branch listing). */
 const app = new Hono();
@@ -18,4 +20,23 @@ app.get('/branches', (c) => {
         return c.json({ error: message }, 500);
     }
 });
+// GET /api/git/orphan-worktrees?projectPath=<path> — list worktrees of a
+// project that are NOT attached to any Kōbō workspace yet.
+app.get('/orphan-worktrees', (c) => {
+    try {
+        const projectPath = c.req.query('projectPath');
+        if (!projectPath) {
+            return c.json({ error: 'Missing required query parameter: projectPath' }, 400);
+        }
+        const db = getDb();
+        const rows = db.prepare('SELECT worktree_path FROM workspaces WHERE project_path = ?').all(projectPath);
+        const attachedPaths = new Set(rows.map((r) => r.worktree_path).filter((p) => !!p));
+        const orphans = listOrphanWorktrees(projectPath, attachedPaths);
+        return c.json(orphans);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
 export default app;

package/dist/server/routes/health.js

@@ -45,13 +45,13 @@ app.get('/report', (c) => {
     const dbSchemaVersion = row?.v ?? 0;
     // Workspaces + worktrees on-disk check
     const workspaces = db
-        .prepare('SELECT id, name, project_path, working_branch, archived_at FROM workspaces')
+        .prepare('SELECT id, name, project_path, working_branch, worktree_path, archived_at FROM workspaces')
         .all();
     const worktreesMissing = [];
     for (const ws of workspaces) {
         if (ws.archived_at)
             continue;
-        const wtPath = path.join(ws.project_path, '.worktrees', ws.working_branch);
+        const wtPath = ws.worktree_path ?? path.join(ws.project_path, '.worktrees', ws.working_branch);
         if (!fs.existsSync(wtPath)) {
             worktreesMissing.push({ workspaceId: ws.id, name: ws.name, path: wtPath, exists: false });
         }

package/dist/server/routes/images.js

@@ -38,7 +38,7 @@ app.post('/:id/images', async (c) => {
         if (buffer.length > MAX_FILE_SIZE) {
             return c.json({ error: `File too large (${(buffer.length / 1024 / 1024).toFixed(1)} MB). Max: 10 MB` }, 400);
         }
-        const worktreePath = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+        const worktreePath = workspace.worktreePath;
         const result = await imageService.saveImage(worktreePath, buffer, file.name);
         return c.json({ uid: result.uid, path: result.relativePath }, 201);
     }
@@ -70,7 +70,7 @@ app.get('/:id/images/file', async (c) => {
         if (!/^(\.ai\/images\/|images\/)[^/]/.test(requested) || requested.includes('..')) {
             return c.json({ error: 'Invalid or disallowed image path' }, 400);
         }
-        const worktreePath = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+        const worktreePath = workspace.worktreePath;
         const imagesRoot = path.resolve(worktreePath, '.ai/images');
         const fullPath = path.resolve(worktreePath, requested);
         // Containment check: fullPath must be a descendant of imagesRoot. `+ path.sep`
@@ -104,7 +104,7 @@ app.delete('/:id/images/:uid', async (c) => {
         if (!workspace) {
             return c.json({ error: `Workspace '${id}' not found` }, 404);
         }
-        const worktreePath = `${workspace.projectPath}/.worktrees/${workspace.workingBranch}`;
+        const worktreePath = workspace.worktreePath;
         await imageService.deleteImage(worktreePath, uid);
         return c.body(null, 204);
     }

package/dist/server/routes/usage.js

@@ -0,0 +1,18 @@
+import { Hono } from 'hono';
+import { refreshNow } from '../services/usage/poller.js';
+const app = new Hono();
+app.post('/:providerId/refresh', async (c) => {
+    const providerId = c.req.param('providerId');
+    try {
+        const snap = await refreshNow(providerId);
+        if (!snap) {
+            return c.json({ error: `Unknown provider '${providerId}'` }, 404);
+        }
+        return c.json({ snapshot: snap }, 200);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return c.json({ error: message }, 500);
+    }
+});
+export default app;