@loicngr/kobo 1.6.8 → 1.6.9

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

@@ -3,6 +3,7 @@ import { nanoid } from 'nanoid';
 import { getDb } from '../../db/index.js';
 import { ensureKoboHome, getCompiledMcpServerPath, getDbPath, getKoboHome, getMcpServerSourcePath, getSettingsPath, getSkillsPath, } from '../../utils/paths.js';
 import { unregisterProcess } from '../../utils/process-tracker.js';
+import * as autoLoopService from '../auto-loop-service.js';
 import { getEffectiveSettings } from '../settings-service.js';
 import * as wakeupService from '../wakeup-service.js';
 import { emitEphemeral } from '../websocket-service.js';
@@ -33,6 +34,8 @@ let availableSkills = (() => {
 })();
 /** workspaceId -> retry count (for quota backoff) */
 const retryCounts = new Map();
+/** Tracks workspaces where the current session failed due to a stale --resume session ID. */
+const resumeFailedSet = new Set();
 /** workspaceId -> backoff timer */
 const backoffTimers = new Map();
 // ── Watchdog ──────────────────────────────────────────────────────────────────
@@ -251,8 +254,33 @@ function reuseOrCreateFreshSession(workspaceId, existingSessionId) {
     return agentSessionId;
 }
 // ── Event handler ─────────────────────────────────────────────────────────────
+/**
+ * Snapshot of the `tasks` done-count at `session:started`, read back and
+ * cleared at `session:ended` to compute the per-session delta. Used by
+ * `auto-loop-service.onSessionEnded` for stall detection.
+ */
+const tasksDoneSnapshot = new Map();
+function getDoneTaskCount(workspaceId) {
+    const db = getDb();
+    const row = db
+        .prepare('SELECT COUNT(*) AS c FROM tasks WHERE workspace_id = ? AND status = ?')
+        .get(workspaceId, 'done');
+    return row.c;
+}
+/** Clear the in-memory done-count snapshot for a workspace (called on delete). */
+export function forgetTasksDoneSnapshot(workspaceId) {
+    tasksDoneSnapshot.delete(workspaceId);
+}
 function handleEvent(workspaceId, agentSessionId, ev) {
     routeEvent(workspaceId, agentSessionId, ev);
+    if (ev.kind === 'rate_limit') {
+        latestRateLimitInfo.set(workspaceId, ev.info);
+    }
+    // Snapshot the done-count at session start so the session:ended hook below
+    // can compute a delta for auto-loop stall detection.
+    if (ev.kind === 'session:started') {
+        tasksDoneSnapshot.set(workspaceId, getDoneTaskCount(workspaceId));
+    }
     if (ev.kind === 'tool:call' && ev.name === 'ScheduleWakeup') {
         const input = ev.input;
         const delay = typeof input?.delaySeconds === 'number' ? input.delaySeconds : 0;
@@ -274,7 +302,10 @@ function handleEvent(workspaceId, agentSessionId, ev) {
     }
     if (ev.kind === 'session:brainstorm-complete') {
         try {
-            updateWorkspaceStatus(workspaceId, 'executing');
+            const ws = getWs(workspaceId);
+            if (ws && ws.status !== 'executing') {
+                updateWorkspaceStatus(workspaceId, 'executing');
+            }
         }
         catch (err) {
             console.error('[orchestrator] Failed to transition to executing:', err);
@@ -283,8 +314,31 @@ function handleEvent(workspaceId, agentSessionId, ev) {
     if (ev.kind === 'error' && ev.category === 'quota') {
         handleQuota(workspaceId, agentSessionId);
     }
+    if (ev.kind === 'error' && ev.category === 'resume_failed') {
+        resumeFailedSet.add(workspaceId);
+        clearStaleEngineSessionId(workspaceId);
+    }
     if (ev.kind === 'session:ended') {
-        onSessionEnded(workspaceId, agentSessionId, ev.exitCode);
+        // Pop the resume_failed flag before any cleanup so both onSessionEnded paths see it.
+        const isResumeFailed = resumeFailedSet.delete(workspaceId);
+        // Compute the auto-loop done-delta BEFORE the internal cleanup because
+        // onSessionEnded(internal) may throw / trigger follow-ups; also read the
+        // snapshot FIRST so a later re-entry can't overwrite it.
+        const before = tasksDoneSnapshot.get(workspaceId) ?? getDoneTaskCount(workspaceId);
+        const after = getDoneTaskCount(workspaceId);
+        const delta = Math.max(0, after - before);
+        tasksDoneSnapshot.delete(workspaceId);
+        // Internal cleanup REMOVES the controller from the map. This must run
+        // BEFORE autoLoopService.onSessionEnded → spawnNextIteration → startAgent,
+        // otherwise startAgent throws "Agent already running" because the
+        // just-ended controller is still in the map.
+        onSessionEnded(workspaceId, agentSessionId, ev.exitCode, isResumeFailed);
+        // When a resume failed the session exited with an error but there's
+        // nothing wrong with the workspace — the stale session ID has been cleared
+        // and the next iteration will start fresh. Treat it as 'completed' so
+        // auto-loop continues without disabling.
+        const effectiveReason = isResumeFailed ? 'completed' : ev.reason;
+        autoLoopService.onSessionEnded(workspaceId, effectiveReason, delta);
     }
     if (ev.kind === 'session:started' && ev.engineSessionId) {
         sessionIds.set(workspaceId, ev.engineSessionId);
@@ -312,7 +366,9 @@ function handleEvent(workspaceId, agentSessionId, ev) {
         }
     }
 }
-function onSessionEnded(workspaceId, agentSessionId, exitCode) {
+function onSessionEnded(workspaceId, agentSessionId, exitCode, resumeFailed = false) {
+    const currentWorkspace = getWs(workspaceId);
+    const preserveQuotaBackoff = currentWorkspace?.status === 'quota';
     const ctrl = controllers.get(workspaceId);
     const wasStopping = ctrl?.status === 'stopping';
     // Identity-preserving cleanup: only remove the controller if the map still
@@ -322,7 +378,9 @@ function onSessionEnded(workspaceId, agentSessionId, exitCode) {
         controllers.delete(workspaceId);
     }
     unregisterProcess(workspaceId);
-    retryCounts.delete(workspaceId);
+    if (!preserveQuotaBackoff) {
+        retryCounts.delete(workspaceId);
+    }
     // Update the agent_sessions row
     try {
         const db = getDb();
@@ -336,13 +394,27 @@ function onSessionEnded(workspaceId, agentSessionId, exitCode) {
         // the "stopped" status. No legacy emit needed.
         return;
     }
-    // Clear any pending backoff timer on non-stopping exits
-    const pendingBackoff = backoffTimers.get(workspaceId);
-    if (pendingBackoff) {
-        clearTimeout(pendingBackoff);
-        backoffTimers.delete(workspaceId);
+    // When the session hit quota, handleQuota() already transitioned the
+    // workspace to `quota` and armed the retry timer. Keep that timer alive
+    // and preserve the `quota` status so auto-loop can resume after reset.
+    if (!preserveQuotaBackoff) {
+        const pendingBackoff = backoffTimers.get(workspaceId);
+        if (pendingBackoff) {
+            clearTimeout(pendingBackoff);
+            backoffTimers.delete(workspaceId);
+        }
+    }
+    if (preserveQuotaBackoff) {
+        try {
+            markWorkspaceUnread(workspaceId);
+            emitEphemeral(workspaceId, 'workspace:unread', { hasUnread: true });
+        }
+        catch {
+            // best-effort
+        }
+        return;
     }
-    if (exitCode !== null && exitCode !== 0) {
+    if (exitCode !== null && exitCode !== 0 && !resumeFailed) {
         try {
             updateWorkspaceStatus(workspaceId, 'error');
         }
@@ -517,12 +589,81 @@ export function getRunningCount() {
     return controllers.size;
 }
 /** Kobo built-in slash commands injected into the skill list (without leading /). */
-const KOBO_COMMANDS = ['kobo-check-progress'];
+const KOBO_COMMANDS = ['kobo-check-progress', 'kobo-prep-autoloop'];
 /** Cached list of slash commands discovered from the last agent init, plus Kobo built-ins. */
 export function getAvailableSkills() {
     return [...KOBO_COMMANDS, ...availableSkills];
 }
 // ── Quota handling ────────────────────────────────────────────────────────────
+/**
+ * Last `rate_limit.info` received per workspace. Used by handleQuota to
+ * schedule the backoff at the actual reset time instead of a hardcoded
+ * exponential. In-memory only — rebuilt on the next rate_limit event after
+ * a server restart.
+ */
+const latestRateLimitInfo = new Map();
+/** Clear the rate-limit info cache for a workspace (called on deleteWorkspace). */
+export function forgetRateLimitInfo(workspaceId) {
+    latestRateLimitInfo.delete(workspaceId);
+}
+/**
+ * Null out the engine_session_id on all agent_sessions rows for a workspace
+ * and clear the in-memory sessionIds cache. Called when a --resume attempt
+ * fails ("No conversation found with session ID") so that the next startAgent
+ * call starts a fresh conversation instead of retrying the stale ID.
+ */
+function clearStaleEngineSessionId(workspaceId) {
+    try {
+        const db = getDb();
+        db.prepare('UPDATE agent_sessions SET engine_session_id = NULL WHERE workspace_id = ?').run(workspaceId);
+        sessionIds.delete(workspaceId);
+    }
+    catch (err) {
+        console.error('[orchestrator] Failed to clear stale engine session ID:', err);
+    }
+}
+const QUOTA_SAFETY_MARGIN_MS = 30_000;
+const QUOTA_MAX_BACKOFF_MS = 24 * 60 * 60 * 1000;
+const QUOTA_SATURATION_THRESHOLD_PCT = 95;
+/**
+ * Fallback backoff ladder (in minutes) used when the `rate_limit` info
+ * isn't usable. Indexed by `retryCount`; anything past the last entry
+ * clamps to the final value (5 h) — long enough to cross a weekly
+ * bucket reset if the rate_limit info truly never arrives.
+ */
+const QUOTA_FALLBACK_LADDER_MINUTES = [15, 30, 60, 180, 300];
+/**
+ * Compute the delay before retrying a workspace hit by quota.
+ *
+ * Prefers the `resetsAt` of the saturated bucket with the furthest-future
+ * reset (a tighter bucket will unlock by then anyway). Falls back to a
+ * fixed ladder (15 → 30 → 60 → 180 → 300 min) whenever the rate_limit
+ * info is missing, malformed, or implausible.
+ */
+export function computeQuotaBackoffMs(workspaceId, retryCount) {
+    const info = latestRateLimitInfo.get(workspaceId);
+    if (info?.buckets?.length) {
+        const candidates = info.buckets
+            .filter((b) => b.usedPct >= QUOTA_SATURATION_THRESHOLD_PCT && typeof b.resetsAt === 'string')
+            .map((b) => ({ resetsAt: b.resetsAt, ts: new Date(b.resetsAt).getTime() }))
+            .filter((x) => !Number.isNaN(x.ts))
+            .sort((a, b) => b.ts - a.ts);
+        const chosen = candidates[0];
+        if (chosen) {
+            const delta = chosen.ts - Date.now() + QUOTA_SAFETY_MARGIN_MS;
+            if (delta > 0 && delta <= QUOTA_MAX_BACKOFF_MS) {
+                return { delayMs: delta, resetsAt: chosen.resetsAt, source: 'rate_limit_info' };
+            }
+        }
+    }
+    const idx = Math.min(Math.max(0, retryCount), QUOTA_FALLBACK_LADDER_MINUTES.length - 1);
+    const backoffMinutes = QUOTA_FALLBACK_LADDER_MINUTES[idx];
+    return { delayMs: backoffMinutes * 60 * 1000, source: 'exponential_fallback' };
+}
+/** @internal Test-only. */
+export function _test_setRateLimitInfo(workspaceId, info) {
+    latestRateLimitInfo.set(workspaceId, info);
+}
 function handleQuota(workspaceId, _agentSessionId) {
     try {
         updateWorkspaceStatus(workspaceId, 'quota');
@@ -533,16 +674,19 @@ function handleQuota(workspaceId, _agentSessionId) {
     // The quota state is already signalled by the `error { category: 'quota' }`
     // AgentEvent that triggered this handler. No legacy `agent:status { quota }`
     // emit needed.
-    // 15min first, then 30min, then 60min cap
+    // Prefer the actual resetsAt from the last rate_limit event; fall back to
+    // the 15/30/60min exponential schedule when that info isn't usable.
     const retryCount = retryCounts.get(workspaceId) ?? 0;
-    const backoffMinutes = Math.min(15 * 2 ** retryCount, 60);
-    const backoffMs = backoffMinutes * 60 * 1000;
+    const { delayMs, resetsAt, source } = computeQuotaBackoffMs(workspaceId, retryCount);
+    const backoffMs = delayMs;
     retryCounts.set(workspaceId, retryCount + 1);
     // Surface the backoff schedule as an ephemeral event so the UI can display
     // retry count / wait time without polluting the persistent event log.
     emitEphemeral(workspaceId, 'agent:quota-backoff', {
         retryCount: retryCount + 1,
-        backoffMinutes,
+        backoffMinutes: Math.round(delayMs / 60_000),
+        resetsAt,
+        source,
     });
     const timer = setTimeout(() => {
         backoffTimers.delete(workspaceId);
@@ -552,8 +696,13 @@ function handleQuota(workspaceId, _agentSessionId) {
                 return;
             }
             try {
-                const freshWorkingDir = `${freshWs.projectPath}/.worktrees/${freshWs.workingBranch}`;
-                startAgent(workspaceId, freshWorkingDir, 'Continue the previous task where you left off.', undefined, true);
+                if (freshWs.autoLoop) {
+                    autoLoopService.onQuotaBackoffExpired(workspaceId);
+                }
+                else {
+                    const freshWorkingDir = `${freshWs.projectPath}/.worktrees/${freshWs.workingBranch}`;
+                    startAgent(workspaceId, freshWorkingDir, 'Continue the previous task where you left off.', undefined, true);
+                }
             }
             catch (err) {
                 console.error(`[orchestrator] Quota retry for workspace '${workspaceId}' failed:`, err);
@@ -597,4 +746,4 @@ export function _runWatchdogForTest() {
     runWatchdog();
 }
 /** Test-only export. Not part of the public module API. */
-export const __test__ = { handleEvent };
+export const __test__ = { handleEvent, handleQuota };

package/dist/server/services/auto-loop-service.js

@@ -0,0 +1,311 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDb } from '../db/index.js';
+import * as orchestrator from './agent/orchestrator.js';
+import { emit, emitEphemeral } from './websocket-service.js';
+import { listTasks } from './workspace-service.js';
+const NO_PROGRESS_STALL_THRESHOLD = 3;
+function getRow(workspaceId) {
+    const db = getDb();
+    const row = db
+        .prepare(`SELECT id, project_path, working_branch, model, permission_mode, reasoning_effort,
+              status, auto_loop, auto_loop_ready, no_progress_streak, archived_at
+       FROM workspaces WHERE id = ?`)
+        .get(workspaceId);
+    return row ?? null;
+}
+function countPendingTasks(workspaceId) {
+    const db = getDb();
+    const row = db
+        .prepare('SELECT COUNT(*) AS c FROM tasks WHERE workspace_id = ? AND status != ?')
+        .get(workspaceId, 'done');
+    return row.c;
+}
+function countDoneTasks(workspaceId) {
+    const db = getDb();
+    const row = db
+        .prepare('SELECT COUNT(*) AS c FROM tasks WHERE workspace_id = ? AND status = ?')
+        .get(workspaceId, 'done');
+    return row.c;
+}
+export function getStatus(workspaceId) {
+    const row = getRow(workspaceId);
+    if (!row)
+        return { auto_loop: false, auto_loop_ready: false, no_progress_streak: 0 };
+    return {
+        auto_loop: row.auto_loop === 1,
+        auto_loop_ready: row.auto_loop_ready === 1,
+        no_progress_streak: row.no_progress_streak,
+    };
+}
+/**
+ * Enable auto-loop for the workspace. Spawns immediately if idle + pending
+ * tasks. If the initial spawn fails (e.g. worktree missing, engine misconfig),
+ * re-throws so the HTTP caller gets a 4xx instead of a silent 200 — the
+ * workspace will already have been auto-disabled by `spawnNextIteration`.
+ */
+export function enable(workspaceId) {
+    const row = getRow(workspaceId);
+    if (!row)
+        throw new Error(`Workspace '${workspaceId}' not found`);
+    if (row.auto_loop_ready !== 1) {
+        throw new Error(`Workspace '${workspaceId}' is not ready for auto-loop (run grooming first)`);
+    }
+    const db = getDb();
+    db.prepare('UPDATE workspaces SET auto_loop = 1, no_progress_streak = 0 WHERE id = ?').run(workspaceId);
+    emitEphemeral(workspaceId, 'autoloop:enabled', {});
+    const pending = countPendingTasks(workspaceId);
+    if (pending === 0)
+        return;
+    if (orchestrator.hasController(workspaceId))
+        return;
+    // spawnNextIteration throws on initial spawn failure (see flag).
+    spawnNextIteration(workspaceId, { throwOnStartAgentError: true });
+}
+/**
+ * Disable auto-loop. Idempotent: if the flag is already 0, returns without
+ * emitting a duplicate `autoloop:disabled` event.
+ */
+export function disable(workspaceId, reason) {
+    const row = getRow(workspaceId);
+    if (!row || row.auto_loop !== 1)
+        return;
+    const db = getDb();
+    db.prepare('UPDATE workspaces SET auto_loop = 0 WHERE id = ?').run(workspaceId);
+    emitEphemeral(workspaceId, 'autoloop:disabled', { reason });
+}
+/**
+ * Route a `session:ended` event into the auto-loop state machine.
+ *
+ * Called by orchestrator.handleEvent. The delta is the number of tasks that
+ * transitioned to `done` during this session (computed from a snapshot taken
+ * at `session:started`).
+ *
+ * When status is `quota` we skip spawning: the orchestrator's handleQuota
+ * already scheduled a backoff timer and will call `onQuotaBackoffExpired` once
+ * the window closes — that function owns the next spawn in that case.
+ */
+export function onSessionEnded(workspaceId, reason, tasksDoneDelta) {
+    const row = getRow(workspaceId);
+    if (!row)
+        return;
+    if (row.auto_loop !== 1)
+        return;
+    // When a quota backoff is in flight (orchestrator.handleQuota scheduled a
+    // timer), let that timer own the next spawn so the backoff delay is respected.
+    if (row.status === 'quota')
+        return;
+    if (reason === 'error' || reason === 'killed') {
+        disable(workspaceId, 'error');
+        return;
+    }
+    // When grooming hasn't run yet (auto_loop_ready=false), the loop is "armed"
+    // but waiting for tasks to be created. Skip streak tracking and task checks —
+    // onAutoLoopReadySet() will trigger the first spawn once grooming completes.
+    if (row.auto_loop_ready !== 1)
+        return;
+    const db = getDb();
+    let streak;
+    if (tasksDoneDelta > 0) {
+        db.prepare('UPDATE workspaces SET no_progress_streak = 0 WHERE id = ?').run(workspaceId);
+        streak = 0;
+    }
+    else {
+        db.prepare('UPDATE workspaces SET no_progress_streak = no_progress_streak + 1 WHERE id = ?').run(workspaceId);
+        streak = row.no_progress_streak + 1;
+    }
+    if (streak >= NO_PROGRESS_STALL_THRESHOLD) {
+        disable(workspaceId, 'stall');
+        return;
+    }
+    if (countPendingTasks(workspaceId) === 0) {
+        disable(workspaceId, 'completed');
+        return;
+    }
+    spawnNextIteration(workspaceId);
+}
+/**
+ * Re-register auto-loop timers at server boot. For every non-archived workspace
+ * with `auto_loop=true` and no active controller, either spawn the next
+ * iteration (if pending tasks exist) or disable with reason=completed.
+ */
+export function rehydrate() {
+    try {
+        const db = getDb();
+        const rows = db.prepare('SELECT id FROM workspaces WHERE auto_loop = 1 AND archived_at IS NULL').all();
+        for (const { id } of rows) {
+            try {
+                if (orchestrator.hasController(id))
+                    continue;
+                if (countPendingTasks(id) === 0) {
+                    disable(id, 'completed');
+                    continue;
+                }
+                spawnNextIteration(id);
+            }
+            catch (err) {
+                console.error(`[auto-loop-service] rehydrate failed for workspace ${id}:`, err);
+            }
+        }
+    }
+    catch (err) {
+        console.error('[auto-loop-service] rehydrate failed:', err);
+    }
+}
+/** Clear in-memory state on workspace delete. Placeholder — nothing cached today. */
+export function forgetAutoLoopState(workspaceId) {
+    void workspaceId;
+}
+// ── Internal ──────────────────────────────────────────────────────────────────
+const PROMPT_TEMPLATE = `[Kōbō auto-loop — iteration #{n}]
+
+Current pending task (highest priority, non-acceptance-criterion first):
+- Task ID: {taskId}
+- Title: {taskTitle}
+- Is acceptance criterion: {isAcceptanceCriterion}
+
+Your job this iteration:
+1. Read \`kobo__list_tasks\` to see all tasks and the big picture.
+2. Implement the SINGLE task above and nothing else. Do not pick a different task.
+3. Run the project's quality checks (lint, typecheck, tests). Check \`.ai/.git-conventions.md\` for the exact commands if unclear.
+4. If checks fail, fix until they pass. If blocked, leave the task unchanged and explain in chat.
+5. Commit with a conventional message (\`feat: [short description]\` or similar per repo conventions).
+6. Code review gate — BEFORE marking the task done, dispatch an independent code-reviewer subagent via the Task tool with \`subagent_type: "code-reviewer"\` (or \`"superpowers:code-reviewer"\` / \`"pr-review-toolkit:code-reviewer"\` — use whichever exists in this environment; fall back to \`superpowers:requesting-code-review\` skill if none is available). Brief the reviewer with: what you just implemented, the task title, and the commit SHA (via \`git rev-parse HEAD\`). Ask specifically whether the change matches the task scope, whether edge cases are handled, and whether the commit is clean.
+7. Act on the review:
+   - If Critical/Important issues: fix them, amend or add a fix-up commit, re-run checks from step 3. Do NOT mark_task_done.
+   - If only Minor issues: fix them if trivial (< 2 min), otherwise note them in the chat and proceed.
+   - If approved with no issues: proceed.
+8. Only if the review cleared (or only minor notes remain), call \`kobo__mark_task_done(taskId="{taskId}")\`.
+
+Do NOT modify other tasks' state. Do NOT create a PR. Do NOT skip the checks.
+Do NOT run \`kill\`, \`pkill\`, \`killall\`, \`pgrep -k\`, or any process-killing command — you may tear down the Kōbō server itself or sibling dev servers. If a dev server needs restarting, let the user do it.
+When you're done (success or blocked), end your turn cleanly.`;
+function pickNextTask(workspaceId) {
+    const pending = listTasks(workspaceId).filter((t) => t.status !== 'done');
+    if (pending.length === 0)
+        return null;
+    // Rule D: non-acceptance first, each group in sort_order (listTasks orders).
+    const nonCriteria = pending.filter((t) => !t.isAcceptanceCriterion);
+    const criteria = pending.filter((t) => t.isAcceptanceCriterion);
+    return [...nonCriteria, ...criteria][0] ?? null;
+}
+function computeIterationNumber(workspaceId) {
+    const done = countDoneTasks(workspaceId);
+    const status = getStatus(workspaceId);
+    return done + status.no_progress_streak + 1;
+}
+/**
+ * Pick the next task, build the prompt, call `orchestrator.startAgent`.
+ *
+ * When called by `onSessionEnded` / `rehydrate`, `startAgent` throws are
+ * swallowed and the loop auto-disables (`reason: 'error'`). When called from
+ * `enable` (initial user-driven spawn), we want the HTTP endpoint to surface
+ * the failure instead of lying with 200, so the caller passes
+ * `throwOnStartAgentError: true` and we re-throw after disabling.
+ *
+ * Worktree-missing edge: if the worktree directory has been deleted on disk,
+ * `orchestrator.startAgent` throws during engine.start — caught below.
+ */
+function spawnNextIteration(workspaceId, opts = {}) {
+    const row = getRow(workspaceId);
+    if (!row)
+        return;
+    const task = pickNextTask(workspaceId);
+    if (!task) {
+        disable(workspaceId, 'completed');
+        return;
+    }
+    const iterationNumber = computeIterationNumber(workspaceId);
+    const prompt = PROMPT_TEMPLATE.replaceAll('{n}', String(iterationNumber))
+        .replaceAll('{taskId}', task.id)
+        .replaceAll('{taskTitle}', task.title)
+        .replaceAll('{isAcceptanceCriterion}', String(task.isAcceptanceCriterion));
+    const worktreePath = path.join(row.project_path, '.worktrees', row.working_branch);
+    // Auto-loop iterations always run in auto-accept mode. Plan mode blocks MCP
+    // tools (kobo__mark_task_done, etc.) and Edit/Write/Bash — everything the
+    // iteration needs — so honoring a 'plan' setting here would deadlock the loop.
+    const permissionMode = 'auto-accept';
+    // Pre-check: if the worktree directory is gone (user `rm -rf`-ed it),
+    // fail loudly rather than letting startAgent throw a deep engine error.
+    if (!fs.existsSync(worktreePath)) {
+        const msg = `Worktree directory missing: ${worktreePath}`;
+        console.error('[auto-loop-service]', msg);
+        disable(workspaceId, 'error');
+        if (opts.throwOnStartAgentError)
+            throw new Error(msg);
+        return;
+    }
+    let agentSessionId;
+    try {
+        const agent = orchestrator.startAgent(workspaceId, worktreePath, prompt, row.model, false, // resume=false — fresh context for each iteration
+        permissionMode, undefined, row.reasoning_effort);
+        agentSessionId = agent.agentSessionId;
+    }
+    catch (err) {
+        console.error('[auto-loop-service] startAgent failed:', err);
+        disable(workspaceId, 'error');
+        if (opts.throwOnStartAgentError)
+            throw err;
+        return;
+    }
+    // Persist the iteration prompt as a system-prompt message so the user can
+    // see exactly what was sent to Claude when they switch to this auto-loop
+    // session in the UI. Tagged with the new agentSessionId so the per-session
+    // filter picks it up only on its own session.
+    emit(workspaceId, 'user:message', { content: prompt, sender: 'system-prompt' }, agentSessionId);
+    const tasksPending = countPendingTasks(workspaceId);
+    const tasksDone = countDoneTasks(workspaceId);
+    emitEphemeral(workspaceId, 'autoloop:iteration-started', {
+        iterationNumber,
+        taskId: task.id,
+        taskTitle: task.title,
+        tasksPending,
+        tasksDone,
+    });
+}
+/**
+ * Called by orchestrator.handleQuota's backoff timer when auto-loop is enabled.
+ * Spawns the next auto-loop iteration if the workspace is still in quota status
+ * with auto_loop active; no-ops otherwise (race-safe).
+ */
+export function onQuotaBackoffExpired(workspaceId) {
+    const row = getRow(workspaceId);
+    if (!row)
+        return;
+    if (row.auto_loop !== 1)
+        return;
+    if (row.status !== 'quota')
+        return;
+    spawnNextIteration(workspaceId);
+}
+/**
+ * Called when a workspace transitions to auto_loop_ready=true (grooming done).
+ * If the loop is armed (auto_loop=1) and tasks exist, spawns the first iteration.
+ * This handles the creation-time autoLoop flag: the brainstorming session ends
+ * without triggering a spawn (auto_loop_ready was false), so this function
+ * starts the loop once the user completes grooming.
+ */
+export function onAutoLoopReadySet(workspaceId) {
+    const row = getRow(workspaceId);
+    if (!row)
+        return;
+    if (row.auto_loop !== 1)
+        return;
+    if (row.archived_at !== null)
+        return;
+    if (orchestrator.hasController(workspaceId))
+        return;
+    if (countPendingTasks(workspaceId) === 0)
+        return;
+    spawnNextIteration(workspaceId);
+}
+// ── Test-only ─────────────────────────────────────────────────────────────────
+/** @internal */
+export function _test_setAutoLoopReady(workspaceId, ready) {
+    const db = getDb();
+    db.prepare('UPDATE workspaces SET auto_loop_ready = ? WHERE id = ?').run(ready ? 1 : 0, workspaceId);
+}
+/** @internal */
+export function _test_pickNextTask(workspaceId) {
+    return pickNextTask(workspaceId);
+}

package/dist/server/services/workspace-service.js

@@ -1,5 +1,7 @@
 import { nanoid } from 'nanoid';
 import { getDb } from '../db/index.js';
+import * as orchestrator from './agent/orchestrator.js';
+import * as autoLoopService from './auto-loop-service.js';
 import * as wakeupService from './wakeup-service.js';
 /** Allowed status transitions per current status. Enforced by updateWorkspaceStatus. */
 const VALID_TRANSITIONS = {
@@ -36,6 +38,9 @@ function mapWorkspace(row) {
         favoritedAt: row.favorited_at,
         tags: parseTags(row.tags),
         engine: row.engine ?? 'claude-code',
+        autoLoop: row.auto_loop === 1,
+        autoLoopReady: row.auto_loop_ready === 1,
+        noProgressStreak: row.no_progress_streak ?? 0,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
     };
@@ -213,6 +218,11 @@ export function deleteWorkspace(id) {
     // The DB row is removed via ON DELETE CASCADE, but the timer would
     // otherwise fire and hit an empty workspace.
     wakeupService.cancel(id, 'deleted');
+    // Drop the cached rate_limit.info so memory doesn't leak on workspace
+    // churn. The Map has no FK to clean up for it automatically.
+    orchestrator.forgetRateLimitInfo(id);
+    orchestrator.forgetTasksDoneSnapshot(id);
+    autoLoopService.forgetAutoLoopState(id);
     const db = getDb();
     db.prepare('DELETE FROM workspaces WHERE id = ?').run(id);
 }
@@ -296,6 +306,9 @@ export function archiveWorkspace(id) {
     }
     // Cancel any pending wakeup — archived workspaces should not wake up.
     wakeupService.cancel(id, 'archived');
+    // Disable auto-loop — archived workspaces should not keep looping.
+    // Idempotent: no-op if auto_loop was already 0.
+    autoLoopService.disable(id, 'user-action');
     const now = new Date().toISOString();
     db.prepare('UPDATE workspaces SET archived_at = ?, updated_at = ? WHERE id = ?').run(now, now, id);
     return getWorkspace(id);
@@ -324,6 +337,15 @@ export function setFavorite(id) {
     }
     return getWorkspace(id);
 }
+/** Flip the `auto_loop_ready` flag for a workspace. Used by the grooming MCP tool + the "Force ready" override. */
+export function setAutoLoopReady(id, ready) {
+    const workspace = getWorkspace(id);
+    if (!workspace)
+        throw new Error(`Workspace '${id}' not found`);
+    const db = getDb();
+    db.prepare('UPDATE workspaces SET auto_loop_ready = ? WHERE id = ?').run(ready ? 1 : 0, id);
+    return getWorkspace(id);
+}
 /** Remove a workspace from favorites. Idempotent: safe to call on a non-favorite, though `updated_at` still refreshes. */
 export function unsetFavorite(id) {
     const db = getDb();

package/dist/shared/auto-loop-prompts.js

@@ -0,0 +1,28 @@
+/**
+ * Single source of truth for the auto-loop grooming instructions.
+ *
+ * Imported BOTH by the client (PREP_AUTOLOOP_PROMPT sent by the "Prepare
+ * for auto-loop" button) and by the server (extended brainstorm prompt
+ * injected at workspace creation when autoLoop=true). Keeping these two
+ * paths aligned was a copy-paste hazard — this file eliminates that.
+ *
+ * `AUTO_LOOP_GROOMING_STEPS` is the numbered workflow, ready to be spliced
+ * into a larger prompt with a one-line intro.
+ *
+ * `AUTO_LOOP_HARD_RULES` is the trailing hard-rules block, same for both.
+ */
+export const AUTO_LOOP_GROOMING_STEPS = `1. Call \`kobo__list_tasks\` FIRST to inspect any pre-existing tasks (they may have been seeded from Notion, a template, or the CreatePage form).
+2. If tasks already exist: DO NOT delete or recreate them from scratch. Read each one, judge whether it is atomic and implementable in one session with clear completion criteria. Improve them in place:
+   - Use \`kobo__update_task\` to rename unclear titles, add completion criteria, or flip \`is_acceptance_criterion\` when needed.
+   - Use \`kobo__create_task\` to SPLIT a task that is too large into smaller atomic pieces (keep the original only if it still makes sense, otherwise update it to one of the split pieces and create the rest).
+   - Use \`kobo__create_task\` to ADD missing acceptance criteria or missing implementation steps the plan requires.
+3. If no tasks exist:
+   - If a plan file exists in \`docs/superpowers/plans/\` or similar, read it and derive the task list from it.
+   - If no plan exists, ask the user what the workspace goal is and propose tasks accordingly.
+   - Create the tasks via \`kobo__create_task\`. For each task, decide \`is_acceptance_criterion\` appropriately.
+4. Call \`kobo__mark_auto_loop_ready\`. This will automatically start the auto-loop, which will pick up the tasks one by one in fresh sessions.`;
+export const AUTO_LOOP_HARD_RULES = `Hard rules:
+- Do NOT touch any source file. No Edit, no Write, no Bash that changes the repo.
+- Do NOT run \`kill\`, \`pkill\`, \`killall\`, \`pgrep -k\`, or any process-killing command — you may tear down the Kōbō server itself or sibling dev servers.
+- Do NOT start implementation even if a plan is ready — auto-loop will drive that afterwards, one task per iteration.
+- If the user asks for changes, re-apply via MCP and re-check. Do NOT mark ready until they approve.`;