@loicngr/kobo 1.11.43 → 1.11.44

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

@@ -0,0 +1,79 @@
+import { getDb } from '../db/index.js';
+import { emitEphemeral } from './websocket-service.js';
+export function listLoopMessages(workspaceId) {
+    return getDb()
+        .prepare(`SELECT id,client_message_id AS clientMessageId,content,state,session_id AS sessionId,
+    created_at AS createdAt FROM auto_loop_messages WHERE workspace_id=? AND state!='delivered' ORDER BY id`)
+        .all(workspaceId);
+}
+export function hasLoopMessage(workspaceId, clientMessageId) {
+    return !!getDb()
+        .prepare('SELECT 1 FROM auto_loop_messages WHERE workspace_id=? AND client_message_id=?')
+        .get(workspaceId, clientMessageId);
+}
+export function enqueueLoopMessage(workspaceId, content, clientMessageId, source) {
+    if (!content.trim() || !clientMessageId.trim())
+        throw new Error('Message content and clientMessageId are required');
+    if (content.length > 100_000 || clientMessageId.length > 200)
+        throw new Error('Message is too large');
+    const db = getDb();
+    db.transaction(() => {
+        const existing = db
+            .prepare('SELECT content,source FROM auto_loop_messages WHERE workspace_id=? AND client_message_id=?')
+            .get(workspaceId, clientMessageId);
+        const encodedSource = source ? JSON.stringify(source) : null;
+        if (existing) {
+            if (existing.content !== content || existing.source !== encodedSource)
+                throw new Error('Message identifier already used with different content');
+            return;
+        }
+        db.prepare('INSERT INTO auto_loop_messages(workspace_id,client_message_id,content,source,created_at) VALUES (?,?,?,?,?)').run(workspaceId, clientMessageId, content, encodedSource, new Date().toISOString());
+        // Instructions received after an earlier validation require a fresh final pass.
+        db.prepare("UPDATE tasks SET status='pending',verification=NULL WHERE workspace_id=? AND role='finalization'").run(workspaceId);
+    })();
+    emitEphemeral(workspaceId, 'autoloop:messages', {});
+}
+/** Claim before dispatch; an interrupted claim must never be replayed blindly. */
+export function claimLoopMessages(workspaceId) {
+    return getDb().transaction(() => {
+        const messages = listLoopMessages(workspaceId).filter((m) => m.state === 'pending');
+        getDb()
+            .prepare("UPDATE auto_loop_messages SET state='dispatching' WHERE workspace_id=? AND state='pending'")
+            .run(workspaceId);
+        return messages;
+    })();
+}
+export function bindLoopMessages(workspaceId, sessionId) {
+    getDb()
+        .prepare("UPDATE auto_loop_messages SET session_id=? WHERE workspace_id=? AND state='dispatching' AND session_id IS NULL")
+        .run(sessionId, workspaceId);
+    emitEphemeral(workspaceId, 'autoloop:messages', {});
+}
+/** Return the number settled by this turn, excluding earlier deliveries on a resumed session. */
+export function settleLoopMessages(workspaceId, sessionId, completed) {
+    if (!sessionId)
+        return 0;
+    const result = getDb()
+        .prepare("UPDATE auto_loop_messages SET state=? WHERE workspace_id=? AND session_id=? AND state='dispatching'")
+        .run(completed ? 'delivered' : 'unknown', workspaceId, sessionId);
+    emitEphemeral(workspaceId, 'autoloop:messages', {});
+    return result.changes;
+}
+export function recoverLoopMessages(workspaceId) {
+    getDb()
+        .prepare("UPDATE auto_loop_messages SET state='unknown' WHERE workspace_id=? AND state='dispatching'")
+        .run(workspaceId);
+}
+export function resolveLoopMessage(workspaceId, id, action) {
+    const row = getDb()
+        .prepare('SELECT state FROM auto_loop_messages WHERE workspace_id=? AND id=?')
+        .get(workspaceId, id);
+    if (!row)
+        throw new Error('Queued message not found');
+    if (action === 'cancel' ? row.state !== 'pending' : row.state !== 'unknown')
+        throw new Error('Message is already being delivered or has been resolved');
+    getDb()
+        .prepare('UPDATE auto_loop_messages SET state=?,session_id=NULL WHERE workspace_id=? AND id=?')
+        .run(action === 'retry' ? 'pending' : 'delivered', workspaceId, id);
+    emitEphemeral(workspaceId, 'autoloop:messages', {});
+}

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

@@ -1,23 +1,26 @@
 import fs from 'node:fs';
-import { buildE2eIterationBlock, buildFinalizationIterationBlock } from '../../shared/auto-loop-prompts.js';
+import { AUTO_LOOP_HARD_RULES, AUTO_LOOP_ITERATION_RULES, buildAutoLoopGroomingSteps, buildE2eIterationBlock, buildFinalizationIterationBlock, } from '../../shared/auto-loop-prompts.js';
 import { getDb } from '../db/index.js';
 import { slugifyProjectName } from '../utils/project-slug.js';
 import { deferUntilWorkspaceAvailable, isWorkspaceLifecycleBusy } from '../utils/workspace-lifecycle-guard.js';
 import { resolveWorkspaceWorktreePath } from '../utils/worktree-paths.js';
 import * as orchestrator from './agent/orchestrator.js';
+import { bindLoopMessages, claimLoopMessages, enqueueLoopMessage, hasLoopMessage, listLoopMessages, recoverLoopMessages, settleLoopMessages, } from './auto-loop-message-service.js';
+import { getRuntime, setRuntime } from './auto-loop-state-service.js';
 import * as cleanupScriptService from './cleanup-script-service.js';
 import * as lifecycleHookService from './lifecycle-hook-service.js';
 import * as quotaBackoffService from './quota-backoff-service.js';
 import * as settingsService from './settings-service.js';
 import { getSuitePrompts } from './skill-suite-prompts.js';
+import { invalidateTaskFinalization } from './task-mutations.js';
 import { emit, emitEphemeral } from './websocket-service.js';
-import { listTasks, updateWorkspaceStatus } from './workspace-service.js';
+import { createTask, listTasks, updateWorkspaceStatus } 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, worktree_path, model, permission_mode, agent_permission_mode, reasoning_effort,
-              status, auto_loop, auto_loop_ready, auto_loop_session_mode, no_progress_streak, archived_at
+              status, auto_loop, auto_loop_ready, auto_loop_session_mode, no_progress_streak, archived_at, worktree_purged_at
        FROM workspaces WHERE id = ?`)
         .get(workspaceId);
     return row ?? null;
@@ -38,25 +41,81 @@ function countDoneTasks(workspaceId) {
 }
 export function getStatus(workspaceId) {
     const row = getRow(workspaceId);
-    if (!row)
-        return { auto_loop: false, auto_loop_ready: false, no_progress_streak: 0 };
+    const runtime = getRuntime(workspaceId, row?.auto_loop_ready === 1);
+    const pending = quotaBackoffService.getPending(workspaceId);
     return {
-        auto_loop: row.auto_loop === 1,
-        auto_loop_ready: row.auto_loop_ready === 1,
-        no_progress_streak: row.no_progress_streak,
+        ...runtime,
+        state: !row?.auto_loop
+            ? runtime.state === 'completed'
+                ? 'completed'
+                : 'stopped'
+            : runtime.state === 'blocked'
+                ? 'blocked'
+                : pending || row.status === 'quota' || row.status === 'awaiting-user' || row.status === 'compacting'
+                    ? 'waiting'
+                    : runtime.state,
+        reason: pending ? pending.reason : row?.status === 'awaiting-user' ? 'awaiting-user' : runtime.reason,
+        retry_at: pending?.targetAt ?? null,
+        auto_loop: row?.auto_loop === 1,
+        auto_loop_ready: row?.auto_loop_ready === 1,
+        no_progress_streak: row?.no_progress_streak ?? 0,
     };
 }
+/** Durable instructions join the next iteration, never a stale engine session. */
+export function queueInstruction(workspaceId, content, clientMessageId, source) {
+    if (hasLoopMessage(workspaceId, clientMessageId)) {
+        enqueueLoopMessage(workspaceId, content, clientMessageId, source);
+        return true;
+    }
+    const row = getRow(workspaceId);
+    if (!row?.auto_loop)
+        return false;
+    if (row.archived_at || row.worktree_purged_at || isWorkspaceLifecycleBusy(workspaceId))
+        throw new Error('Workspace is unavailable');
+    enqueueLoopMessage(workspaceId, content, clientMessageId, source);
+    spawnNextIteration(workspaceId);
+    return true;
+}
+/** Incomplete work keeps its intent, but requires an explicit human resume. */
+export function block(workspaceId, reason) {
+    if (getRow(workspaceId)?.auto_loop !== 1)
+        return;
+    quotaBackoffService.cancel(workspaceId, 'completed');
+    setRuntime(workspaceId, { state: 'blocked', reason });
+}
+/** Shared admission gate for all unattended starts. */
+export function canStartAutomatically(workspaceId) {
+    const row = getRow(workspaceId);
+    return (!!row &&
+        !row.archived_at &&
+        !row.worktree_purged_at &&
+        !orchestrator.isShuttingDown() &&
+        !isWorkspaceLifecycleBusy(workspaceId) &&
+        !orchestrator.hasController(workspaceId) &&
+        !['awaiting-user', 'compacting'].includes(row.status) &&
+        // A manual workspace keeps its quota status after expiry. Its explicit
+        // wakeup/cron may resume then; an enabled loop still belongs to quota recovery.
+        !(row.status === 'quota' && row.auto_loop === 1) &&
+        !quotaBackoffService.getPending(workspaceId) &&
+        getRuntime(workspaceId).state !== 'blocked' &&
+        hasFreeAgentSlot());
+}
 /**
  * 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`.
+ * re-throws so the HTTP caller gets a 4xx; the mission remains explicitly blocked.
  */
 export function enable(workspaceId) {
     const row = getRow(workspaceId);
     if (!row)
         throw new Error(`Workspace '${workspaceId}' not found`);
-    if (row.auto_loop_ready !== 1) {
+    if (row.archived_at)
+        throw new Error(`Workspace '${workspaceId}' is already archived`);
+    if (row.worktree_purged_at)
+        throw new Error(`Workspace '${workspaceId}' is unavailable`);
+    if (isWorkspaceLifecycleBusy(workspaceId))
+        throw new Error(`Workspace '${workspaceId}' is busy`);
+    if (row.auto_loop_ready !== 1 && !row.auto_loop) {
         throw new Error(`Workspace '${workspaceId}' is not ready for auto-loop (run grooming first)`);
     }
     // Refuse to enable when there is nothing to spawn — without this, auto_loop
@@ -64,11 +123,24 @@ export function enable(workspaceId) {
     // (auto-loop banner) without doing any work. The user must add a task or
     // unmark a done task before re-enabling.
     const pending = countPendingTasks(workspaceId);
-    if (pending === 0) {
+    if (pending === 0 && !row.auto_loop) {
         throw new Error(`Workspace '${workspaceId}' has no pending tasks; add or unmark a task before enabling auto-loop`);
     }
+    if (getRuntime(workspaceId).state === 'blocked' &&
+        row.status === 'quota' &&
+        !quotaBackoffService.getPending(workspaceId) &&
+        !orchestrator.hasController(workspaceId))
+        updateWorkspaceStatus(workspaceId, 'idle');
     const db = getDb();
     db.prepare('UPDATE workspaces SET auto_loop = 1, no_progress_streak = 0 WHERE id = ?').run(workspaceId);
+    orchestrator.resetAutoLoopRetries(workspaceId);
+    db.prepare('DELETE FROM auto_loop_progress WHERE workspace_id=?').run(workspaceId);
+    setRuntime(workspaceId, {
+        state: 'waiting',
+        reason: null,
+        diagnostic_attempts: 0,
+        phase: row.auto_loop_ready ? 'execution' : 'grooming',
+    });
     emitEphemeral(workspaceId, 'autoloop:enabled', {});
     if (orchestrator.hasController(workspaceId))
         return;
@@ -83,7 +155,13 @@ export function disable(workspaceId, reason) {
     const row = getRow(workspaceId);
     if (row?.auto_loop !== 1)
         return;
+    if (reason === 'error' || reason === 'stall' || reason === 'awaiting-clarification') {
+        block(workspaceId, reason);
+        return;
+    }
     const db = getDb();
+    quotaBackoffService.cancel(workspaceId, 'completed');
+    setRuntime(workspaceId, { state: reason === 'completed' ? 'completed' : 'stopped', reason });
     db.prepare('UPDATE workspaces SET auto_loop = 0 WHERE id = ?').run(workspaceId);
     const diagnostic = {
         reason,
@@ -94,9 +172,7 @@ export function disable(workspaceId, reason) {
     console.info(`[auto-loop] disabled workspace '${workspaceId}' reason=${reason}` +
         ` pending=${diagnostic.tasksPending} streak=${diagnostic.noProgressStreak} status=${diagnostic.status}`);
     emitEphemeral(workspaceId, 'autoloop:disabled', diagnostic);
-    // The user's own hook, if they wrote one. Deliberately fired for EVERY
-    // reason, not only 'completed' like the cleanup script below: a loop that
-    // stalled is precisely the case worth being told about.
+    // Only actual disable transitions fire this hook. A blocked mission retains its intent.
     void lifecycleHookService.onAutoLoopDisabled(workspaceId, {
         reason,
         tasksPending: diagnostic.tasksPending,
@@ -114,17 +190,26 @@ export function disable(workspaceId, reason) {
  * Called by orchestrator.handleEvent. The delta records whether task state
  * progressed during this session, including transitions such as pending to
  * in_progress, not only completion.
+ * Instruction-intake turns preserve the stagnation budget: their prompt only
+ * integrates requirements. The orchestrator reports them after settling delivery.
  *
  * 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, taskProgressDelta) {
+export function onSessionEnded(workspaceId, reason, taskProgressDelta, instructionIntake = false) {
     const row = getRow(workspaceId);
     if (!row)
         return;
     if (row.auto_loop !== 1)
         return;
+    const settledInstructions = settleLoopMessages(workspaceId, getRuntime(workspaceId).current_session_id, reason === 'completed');
+    // The orchestrator may already have settled this exact turn's deliveries.
+    instructionIntake ||= settledInstructions > 0;
+    if (listLoopMessages(workspaceId).some((m) => m.state === 'unknown')) {
+        block(workspaceId, 'message-delivery-unknown');
+        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')
@@ -140,30 +225,24 @@ export function onSessionEnded(workspaceId, reason, taskProgressDelta) {
     if (reason === 'watchdog')
         return;
     if (reason === 'error') {
-        disable(workspaceId, 'error');
+        block(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)
+    if (getRuntime(workspaceId).state === 'blocked')
         return;
-    const db = getDb();
-    let streak;
-    if (taskProgressDelta > 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');
+    if (row.auto_loop_ready === 1 && countPendingTasks(workspaceId) === 0 && listLoopMessages(workspaceId).length === 0) {
+        spawnNextIteration(workspaceId);
         return;
     }
-    if (countPendingTasks(workspaceId) === 0) {
-        disable(workspaceId, 'completed');
+    const db = getDb();
+    const runtime = getRuntime(workspaceId);
+    const streak = taskProgressDelta > 0 ? 0 : row.no_progress_streak + (instructionIntake ? 0 : 1);
+    db.prepare('UPDATE workspaces SET no_progress_streak=? WHERE id=?').run(streak, workspaceId);
+    if (taskProgressDelta > 0)
+        setRuntime(workspaceId, { diagnostic_attempts: 0 });
+    // One diagnostic session after three stagnant iterations, followed by two attempts.
+    if (!instructionIntake && taskProgressDelta <= 0 && runtime.diagnostic_attempts >= 3) {
+        block(workspaceId, 'No progress after diagnostic and two further attempts. Review the session findings and resume after resolving the blocker.');
         return;
     }
     spawnNextIteration(workspaceId);
@@ -176,24 +255,33 @@ export function onSessionEnded(workspaceId, reason, taskProgressDelta) {
 export function rehydrate() {
     try {
         const db = getDb();
+        const interrupted = db
+            .prepare("SELECT DISTINCT workspace_id FROM auto_loop_messages WHERE state='dispatching'")
+            .all();
+        for (const row of interrupted)
+            if (!orchestrator.hasController(row.workspace_id))
+                recoverLoopMessages(row.workspace_id);
         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;
-                // Workspaces still in grooming (ready=0) have their session killed by
-                // the server reload. Don't disable — the user can re-trigger grooming
-                // manually. Auto-disable on missing pending tasks would also fire here
-                // if the agent hadn't yet seeded any task before the reload.
-                const row = getRow(id);
-                if (row?.auto_loop_ready !== 1)
+                recoverLoopMessages(id);
+                if (listLoopMessages(id).some((m) => m.state === 'unknown')) {
+                    block(id, 'message-delivery-unknown');
                     continue;
-                // Persisted quota timers own the restart of these workspaces. Boot
-                // restores them after this pass; starting here bypasses their delay.
-                if (row.status === 'quota')
+                }
+                if (getRuntime(id).state === 'blocked')
                     continue;
-                if (countPendingTasks(id) === 0) {
-                    disable(id, 'completed');
+                const row = getRow(id);
+                if (row?.status === 'quota') {
+                    if (!quotaBackoffService.getPending(id))
+                        quotaBackoffService.arm(id, 15_000, {
+                            resetsAt: null,
+                            source: 'fallback_ladder',
+                            reason: 'quota',
+                            retryCount: 1,
+                        });
                     continue;
                 }
                 spawnNextIteration(id);
@@ -214,7 +302,7 @@ export function forgetAutoLoopState(workspaceId) {
 // ── Internal ──────────────────────────────────────────────────────────────────
 const PROMPT_TEMPLATE = `[Kōbō auto-loop — iteration #{n}{sessionModeSuffix}]
 
-Current pending task (highest priority, non-acceptance-criterion first):
+Current pending task (workspace order; finalization follows all todos and criteria):
 - Task ID: {taskId}
 - Title: {taskTitle}
 - Is acceptance criterion: {isAcceptanceCriterion}
@@ -254,21 +342,31 @@ 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;
+    return pending.find((t) => !isFinalTask(t)) ?? pending[0] ?? null;
 }
-function computeIterationNumber(workspaceId) {
-    const done = countDoneTasks(workspaceId);
-    const status = getStatus(workspaceId);
-    return done + status.no_progress_streak + 1;
+function isFinalTask(task) {
+    return task.role === 'finalization';
+}
+function ensureFinalVerification(workspaceId) {
+    const tasks = listTasks(workspaceId);
+    if (!tasks.some(isFinalTask)) {
+        createTask(workspaceId, {
+            title: '[FINAL] Verify all todos and acceptance criteria',
+            sortOrder: Math.max(-1, ...tasks.map((t) => t.sortOrder)) + 1,
+        });
+    }
+    else {
+        // Legacy completed finalizations have no evidence: preserve work but revalidate completion.
+        getDb()
+            .prepare("UPDATE tasks SET status='pending' WHERE workspace_id=? AND role='finalization' AND status='done' AND verification IS NULL")
+            .run(workspaceId);
+    }
 }
 /**
  * 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
+ * swallowed and the loop is blocked with the failure reason. 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.
@@ -303,7 +401,7 @@ export function resumeWaitingWorkspaces(excluded = new Set()) {
     const db = getDb();
     const rows = db
         .prepare(`SELECT id, status FROM workspaces
-        WHERE auto_loop = 1 AND auto_loop_ready = 1 AND archived_at IS NULL
+        WHERE auto_loop = 1 AND archived_at IS NULL
         ORDER BY updated_at ASC`)
         .all();
     for (const row of rows) {
@@ -334,29 +432,35 @@ function spawnNextIteration(workspaceId, opts = {}) {
         return;
     if (deferUntilWorkspaceAvailable(workspaceId, resumeWaitingWorkspaces))
         return;
-    if (orchestrator.hasController(workspaceId))
-        return;
-    // Same guard as onSessionEnded — never race a deferred-resume start.
-    if (row.status === 'awaiting-user' || row.status === 'compacting')
+    if (!canStartAutomatically(workspaceId)) {
+        if (getRuntime(workspaceId).state !== 'blocked' && !orchestrator.hasController(workspaceId)) {
+            setRuntime(workspaceId, { state: 'waiting', reason: row.status === 'quota' ? 'quota' : 'capacity-or-lifecycle' });
+            if (!hasFreeAgentSlot())
+                emitEphemeral(workspaceId, 'autoloop:waiting-for-slot', {
+                    running: orchestrator.runningAgentCount(),
+                    limit: settingsService.getGlobalSettings().maxConcurrentAgents,
+                });
+        }
         return;
-    const task = pickNextTask(workspaceId);
-    if (!task) {
-        disable(workspaceId, 'completed');
+    }
+    if (listLoopMessages(workspaceId).some((m) => m.state === 'unknown' || m.state === 'dispatching')) {
+        block(workspaceId, 'message-delivery-unknown');
         return;
     }
-    // Hold off rather than pile on. Ten auto-loop workspaces waking together
-    // hammer the same rate limit and each land in their own backoff, so nobody
-    // gets through. The loop stays enabled: the next session to end anywhere
-    // calls back in here, and by then a slot has freed.
-    if (!hasFreeAgentSlot()) {
-        console.log(`[auto-loop] workspace '${workspaceId}' is waiting for a free agent slot`);
-        emitEphemeral(workspaceId, 'autoloop:waiting-for-slot', {
-            running: orchestrator.runningAgentCount(),
-            limit: settingsService.getGlobalSettings().maxConcurrentAgents,
-        });
+    const grooming = row.auto_loop_ready !== 1;
+    if (listLoopMessages(workspaceId).some((m) => m.state === 'pending'))
+        invalidateTaskFinalization(getDb(), workspaceId);
+    if (!grooming)
+        ensureFinalVerification(workspaceId);
+    const task = grooming ? null : pickNextTask(workspaceId);
+    const pendingInstructions = listLoopMessages(workspaceId).filter((m) => m.state === 'pending');
+    if (!grooming && !task && pendingInstructions.length === 0) {
+        disable(workspaceId, 'completed');
         return;
     }
-    const iterationNumber = computeIterationNumber(workspaceId);
+    const runtime = getRuntime(workspaceId);
+    const diagnostic = row.no_progress_streak >= NO_PROGRESS_STALL_THRESHOLD && runtime.diagnostic_attempts === 0;
+    const iterationNumber = runtime.iteration + 1;
     // Override block: replaces the standard iteration prompt body when the task
     // title carries a recognized prefix (case-sensitive, trailing space required).
     // Empty string otherwise so the placeholder collapses cleanly in PROMPT_TEMPLATE.
@@ -367,20 +471,30 @@ function spawnNextIteration(workspaceId, opts = {}) {
     // Finalization cascades project || global; E2E stays project-only.
     const finalizationSettings = settingsService.getEffectiveFinalization(row.project_path);
     let overrideBlock = '';
-    if (task.title.startsWith('[FINAL] ')) {
+    if (task && isFinalTask(task)) {
         overrideBlock = buildFinalizationIterationBlock(finalizationSettings);
     }
-    else if (task.title.startsWith('[E2E] ') && e2eSettings.framework) {
+    else if (task?.title.startsWith('[E2E] ') && e2eSettings.framework) {
         overrideBlock = buildE2eIterationBlock(e2eSettings);
     }
     const continuousSession = row.auto_loop_session_mode === 'continuous';
-    const prompt = PROMPT_TEMPLATE.replaceAll('{n}', String(iterationNumber))
+    let prompt = PROMPT_TEMPLATE.replaceAll('{n}', String(iterationNumber))
         .replaceAll('{sessionModeSuffix}', continuousSession ? ', session continue' : '')
-        .replaceAll('{taskId}', task.id)
-        .replaceAll('{taskTitle}', task.title)
-        .replaceAll('{isAcceptanceCriterion}', String(task.isAcceptanceCriterion))
+        .replaceAll('{taskId}', task?.id ?? '')
+        .replaceAll('{taskTitle}', task?.title ?? '')
+        .replaceAll('{isAcceptanceCriterion}', String(task?.isAcceptanceCriterion ?? false))
         .replaceAll('{overrideBlock}', overrideBlock)
         .replaceAll('{reviewGate}', getActiveAutoLoopReviewGate());
+    if (grooming)
+        prompt = `[Kōbō auto-loop — resume grooming]
+Resume the interrupted preparation. Read the workspace conversation with kobo__read_workspace_events_csv, recover the user's goal and constraints, and inspect existing tasks before making changes. Do not duplicate tasks.
+${buildAutoLoopGroomingSteps(e2eSettings, finalizationSettings)}
+${AUTO_LOOP_HARD_RULES}`;
+    if (diagnostic)
+        prompt = `[Kōbō auto-loop — diagnostic]
+Three iterations produced no task progress. Read recent workspace events, explain the blocker, and try a different approach or decompose the task. Never mark unfinished or unverified work done. If intervention is required, state the precise action needed.
+${prompt}`;
+    prompt += `\n${AUTO_LOOP_ITERATION_RULES}`;
     const globalSettings = settingsService.getGlobalSettings();
     const projectSlug = globalSettings.worktreesPrefixByProject
         ? slugifyProjectName(projectSettings?.displayName ?? '', row.project_path)
@@ -400,12 +514,15 @@ function spawnNextIteration(workspaceId, opts = {}) {
     if (!fs.existsSync(worktreePath)) {
         const msg = `Worktree directory missing: ${worktreePath}`;
         console.error('[auto-loop-service]', msg);
-        disable(workspaceId, 'error');
+        block(workspaceId, msg);
         if (opts.throwOnStartAgentError)
             throw new Error(msg);
         return;
     }
     let agentSessionId;
+    const instructions = claimLoopMessages(workspaceId);
+    if (instructions.length)
+        prompt = `[Kōbō auto-loop — integrate user instructions]\nRead kobo__list_tasks and relevant workspace history. Integrate the following instructions into the todos and acceptance criteria, preserving the user's constraints. Update existing tasks and create missing ones before ending this turn. Do not implement or finalize work during this intake turn: the next iteration will select the updated highest-priority task. Leave finalization open.\n${instructions.map((m) => `- ${m.content}`).join('\n')}\n${grooming ? prompt : AUTO_LOOP_ITERATION_RULES}`;
     try {
         const agent = orchestrator.startAgent(workspaceId, worktreePath, prompt, row.model, 
         // resume=false spawns a fresh session per iteration (default); resume=true
@@ -414,12 +531,34 @@ function spawnNextIteration(workspaceId, opts = {}) {
         // prior session to resume (e.g. the very first iteration), orchestrator's
         // resolveSessionForResume gracefully falls back to a fresh session — no
         // special-casing needed here.
-        continuousSession, agentPermissionMode, undefined, row.reasoning_effort);
+        grooming || continuousSession, agentPermissionMode, undefined, row.reasoning_effort);
         agentSessionId = agent.agentSessionId;
+        if (agentSessionId)
+            bindLoopMessages(workspaceId, agentSessionId);
+        setRuntime(workspaceId, {
+            phase: grooming ? 'grooming' : task && isFinalTask(task) ? 'finalization' : 'execution',
+            state: 'active',
+            reason: null,
+            iteration: iterationNumber,
+            current_task_id: task?.id ?? null,
+            current_session_id: agentSessionId ?? null,
+            // An intake prompt replaces the diagnostic/work prompt and forbids implementation.
+            diagnostic_attempts: instructions.length
+                ? runtime.diagnostic_attempts
+                : diagnostic
+                    ? 1
+                    : runtime.diagnostic_attempts > 0
+                        ? runtime.diagnostic_attempts + 1
+                        : 0,
+        });
     }
     catch (err) {
+        // Synchronous rejection precedes dispatch; return only this unbound claim to the queue.
+        getDb()
+            .prepare("UPDATE auto_loop_messages SET state='pending' WHERE workspace_id=? AND state='dispatching' AND session_id IS NULL")
+            .run(workspaceId);
         console.error('[auto-loop-service] startAgent failed:', err);
-        disable(workspaceId, 'error');
+        block(workspaceId, err instanceof Error ? err.message : String(err));
         if (opts.throwOnStartAgentError)
             throw err;
         return;
@@ -433,8 +572,8 @@ function spawnNextIteration(workspaceId, opts = {}) {
     const tasksDone = countDoneTasks(workspaceId);
     emitEphemeral(workspaceId, 'autoloop:iteration-started', {
         iterationNumber,
-        taskId: task.id,
-        taskTitle: task.title,
+        taskId: task?.id ?? null,
+        taskTitle: task?.title ?? 'Grooming',
         tasksPending,
         tasksDone,
     });

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

@@ -0,0 +1,30 @@
+import { getDb } from '../db/index.js';
+import { emitEphemeral } from './websocket-service.js';
+export function getRuntime(workspaceId, ready = false) {
+    const row = getDb()
+        .prepare(`SELECT phase,state,reason,iteration,diagnostic_attempts,current_task_id,current_session_id
+    FROM auto_loop_runs WHERE workspace_id=?`)
+        .get(workspaceId);
+    return (row ?? {
+        phase: ready ? 'execution' : 'grooming',
+        state: 'waiting',
+        reason: null,
+        iteration: 0,
+        diagnostic_attempts: 0,
+        current_task_id: null,
+        current_session_id: null,
+    });
+}
+export function setRuntime(workspaceId, patch) {
+    const current = { ...getRuntime(workspaceId), ...patch };
+    getDb()
+        .prepare(`INSERT INTO auto_loop_runs
+    (workspace_id,phase,state,reason,iteration,diagnostic_attempts,current_task_id,current_session_id,updated_at)
+    VALUES (@id,@phase,@state,@reason,@iteration,@diagnostic_attempts,@current_task_id,@current_session_id,@now)
+    ON CONFLICT(workspace_id) DO UPDATE SET phase=excluded.phase,state=excluded.state,reason=excluded.reason,
+    iteration=excluded.iteration,diagnostic_attempts=excluded.diagnostic_attempts,current_task_id=excluded.current_task_id,
+    current_session_id=excluded.current_session_id,updated_at=excluded.updated_at`)
+        .run({ ...current, id: workspaceId, now: new Date().toISOString() });
+    emitEphemeral(workspaceId, 'autoloop:state', current);
+    return current;
+}