@boopkit/cli 0.6.18 → 0.7.1

package/dist/capability-versions.json

@@ -1,22 +1,22 @@
 {
   "@boopkit/cap-api": "0.4.5",
-  "@boopkit/cap-background-jobs": "0.4.3",
+  "@boopkit/cap-background-jobs": "0.5.0",
   "@boopkit/cap-cloud-storage": "0.5.0",
-  "@boopkit/cap-coding": "0.4.6",
-  "@boopkit/cap-database": "0.4.4",
-  "@boopkit/cap-email": "0.4.3",
+  "@boopkit/cap-coding": "0.4.7",
+  "@boopkit/cap-database": "0.4.5",
+  "@boopkit/cap-email": "0.4.4",
   "@boopkit/cap-hello": "0.4.1",
   "@boopkit/cap-noticeboard": "0.4.1",
   "@boopkit/cap-oauth-client": "0.1.1",
-  "@boopkit/cap-oauth-server": "0.1.4",
-  "@boopkit/cap-product-design": "0.6.10",
-  "@boopkit/cap-project-mgmt": "0.4.11",
+  "@boopkit/cap-oauth-server": "0.3.1",
+  "@boopkit/cap-product-design": "0.6.11",
+  "@boopkit/cap-project-mgmt": "0.4.12",
   "@boopkit/cap-services": "0.4.3",
   "@boopkit/cap-skills": "0.5.6",
-  "@boopkit/cap-testing": "0.5.7",
-  "@boopkit/cap-users": "0.8.1",
+  "@boopkit/cap-testing": "0.5.8",
+  "@boopkit/cap-users": "0.9.0",
   "@boopkit/cap-ux": "0.2.3",
-  "@boopkit/cap-web": "0.5.5",
+  "@boopkit/cap-web": "0.5.6",
   "@boopkit/cap-workflows": "0.2.2",
   "@boopkit/logger": "0.4.0"
 }

package/dist/commands/loop.d.ts

@@ -29,6 +29,13 @@ export interface LoopOptions {
     watch?: boolean;
     reuseSession?: boolean;
 }
+interface IssueInfo {
+    id: string;
+    title: string;
+    priority: string;
+    issue_type: string;
+    description: string;
+}
 interface ClaudeRunResult {
     exitCode: number;
     limitHit: boolean;
@@ -36,6 +43,14 @@ interface ClaudeRunResult {
     peakContext?: number;
     /** The model's context window (tokens), from the result's modelUsage. */
     contextWindow?: number;
+    /** How many tools the session called. None means it did no work (see sessionDidWork). */
+    toolCalls?: number;
+    /**
+     * What the session said as it ended: the text of its result, or failing that
+     * its last message, or failing that the last line it wrote to stderr. When a
+     * session fails to start, this is where the cause is named.
+     */
+    finalText?: string;
 }
 export interface PlanResult {
     featureId: string | null;
@@ -229,6 +244,15 @@ export declare function getMatchingReadyIssues(prefix: string, includeFeatures:
         maxBuffer?: number;
     }) => string;
 }): ReadyIssue[];
+/**
+ * The instructions every loop session starts from. A session acts on this text
+ * literally and reads it whether or not it opens a skill, so step 5 carries the
+ * test-run rule itself (focused tests plus the static check; the full suite only
+ * when the issue asks) and names no command, because the text is the same in
+ * every project and the commands are not. For the same reason it names no
+ * project.
+ */
+export declare function buildPrompt(issue: IssueInfo): string;
 /**
  * Default per-issue budget cap in USD. The planning phase and each task each get
  * this cap. Single source of truth — imported by cli.ts for its --budget help
@@ -243,12 +267,48 @@ export declare const DEFAULT_BUDGET_USD = "25.00";
  * also skips resuming a `blocked` issue entirely (see shouldResumeUnclosedIssue)
  * — this clause is the belt-and-suspenders for a block raised mid-resume.
  */
-export declare const RESUME_PROMPT = "The previous session ended without closing this issue. Reload the state and continue.\n\nIMPORTANT: If the previous session marked this issue blocked with a diagnostic, the block stands. Do not re-open it or work around it. Read the issue's notes and the previous session's commits, confirm the block is still appropriate, and stop without taking further action.\n\nOtherwise, complete the workflow:\n- Finish any remaining implementation\n- Run tests to verify\n- Commit changes referencing the issue ID\n- Close the issue with bd close\n- Push with: git pull --rebase && git push\n\nDo not pause for review of completed work. Complete everything now.";
+export declare const RESUME_PROMPT = "The previous session ended without closing this issue. Reload the state and continue.\n\nIMPORTANT: If the previous session marked this issue blocked with a diagnostic, the block stands. Do not re-open it or work around it. Read the issue's notes and the previous session's commits, confirm the block is still appropriate, and stop without taking further action.\n\nOtherwise, complete the workflow:\n- Finish any remaining implementation\n- Run the tests that step 5 of your first instructions describes: the issue's own test scope if it states one, otherwise the focused tests for what you changed plus the static check, and not the full suite unless the issue asks for it\n- Commit changes referencing the issue ID\n- Close the issue with bd close\n- Push with: git pull --rebase && git push\n\nDo not pause for review of completed work. Complete everything now.";
 /**
  * Decide whether a reused session should rotate before taking the next issue.
  * Rotates once peak observed occupancy reaches ROTATE_FRACTION of the window.
  * Pure so it is unit-testable without a running loop.
  */
 export declare function shouldRotateSession(peakContext: number, contextWindow: number, fraction?: number): boolean;
-export declare function runLoop(options: LoopOptions): Promise<void>;
+/**
+ * How many sessions in a row may end without doing any work before the loop
+ * stops. Fixed, with no flag: no caller needs a different number. A claim that
+ * fails before a session starts counts as one such session (boop-rfof).
+ *
+ * A claim that cannot start work costs four sessions at the default
+ * --resume-limit (the first run plus three resumes), so five means the loop has
+ * claimed an issue a second time and that claim did not start either. In the
+ * incident this rule comes from (boop-to45.2), expired credentials produced
+ * 1,543 such sessions in 64 minutes, each one turn long and over within a second.
+ */
+export declare const NO_WORK_SESSION_LIMIT = 5;
+/**
+ * Whether a session did any work, which here means it called at least one tool.
+ * A session cannot read a file, claim its issue or run a command without one,
+ * so a session with no tool calls started nothing, whatever the reason: expired
+ * or missing credentials, an upstream outage, a `claude` binary that is not
+ * there. The test deliberately ignores how long the session lasted and what its
+ * error said, because an outage that retries for a minute before giving up is
+ * the same fault as a credential check that fails at once.
+ */
+export declare function sessionDidWork(run: ClaudeRunResult): boolean;
+/**
+ * Split a session's stream-json output into complete lines. A stdout chunk ends
+ * wherever the pipe buffer happened to fill, so the last piece of a chunk may be
+ * the first part of a line whose remainder arrives in the next chunk: it comes
+ * back as `rest`, for the caller to pass in as `carry` with the next chunk and
+ * to flush when the stream closes. Pure so a test can feed it a line cut in two.
+ */
+export declare function splitStreamLines(carry: string, chunk: string): {
+    lines: string[];
+    rest: string;
+};
+export declare function runLoop(options: LoopOptions, deps?: {
+    /** Runs one Claude session for an issue. Tests substitute this; the planning phase is not affected. */
+    runClaudeFn?: RunClaudeFn;
+}): Promise<void>;
 export {};

package/dist/commands/loop.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESUME_PROMPT = exports.DEFAULT_BUDGET_USD = exports.DEFAULT_MODEL = exports.BD_READ_MAX_BUFFER = void 0;
+exports.NO_WORK_SESSION_LIMIT = exports.RESUME_PROMPT = exports.DEFAULT_BUDGET_USD = exports.DEFAULT_MODEL = exports.BD_READ_MAX_BUFFER = void 0;
 exports.assertDoltServerMode = assertDoltServerMode;
 exports.discoverDoltServer = discoverDoltServer;
 exports.resolveDefaultBranch = resolveDefaultBranch;
@@ -52,12 +52,16 @@ exports.isIssueInScope = isIssueInScope;
 exports.isClaimableReadyIssue = isClaimableReadyIssue;
 exports.shouldCloseFeatureRoot = shouldCloseFeatureRoot;
 exports.getMatchingReadyIssues = getMatchingReadyIssues;
+exports.buildPrompt = buildPrompt;
 exports.shouldRotateSession = shouldRotateSession;
+exports.sessionDidWork = sessionDidWork;
+exports.splitStreamLines = splitStreamLines;
 exports.runLoop = runLoop;
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const crypto_1 = require("crypto");
+const string_decoder_1 = require("string_decoder");
 /**
  * Output cap for every `bd … --json` read the loop makes.
  *
@@ -879,8 +883,16 @@ function isIssueClosed(id) {
         return false;
     }
 }
+/**
+ * The instructions every loop session starts from. A session acts on this text
+ * literally and reads it whether or not it opens a skill, so step 5 carries the
+ * test-run rule itself (focused tests plus the static check; the full suite only
+ * when the issue asks) and names no command, because the text is the same in
+ * every project and the commands are not. For the same reason it names no
+ * project.
+ */
 function buildPrompt(issue) {
-    return `You are working on issue ${issue.id} in the boop project.
+    return `You are working on issue ${issue.id} in this project.
 
 ## Issue: ${issue.title}
 Type: ${issue.issue_type} | Priority: ${issue.priority}
@@ -893,7 +905,10 @@ ${issue.description}
 2. Claim the issue: bd update ${issue.id} --claim
 3. Read relevant skills from skills/ (list folders, read each SKILL.md) before making changes
 4. Implement the changes following TDD-Lite: observe, implement, verify
-5. Run tests if applicable: npm test
+5. Run the tests this issue needs, and no more:
+   - If the issue description states which tests to run, run exactly those and skip the rest of this step. The issue's scope replaces the default below; do not run both.
+   - Otherwise, run the focused tests for the files you changed, plus the project's whole-program static check. The boop-testing-testing skill (skills/boop-testing-testing/SKILL.md) and the PROJECT.md beside it give this project's commands for both. If the project has no static check, run the focused tests alone.
+   - Run the full test suite only when the issue description asks for it. It runs once per branch, on the task that completes the branch, and not on the tasks before it.
 6. Commit your changes with a message referencing ${issue.id}
 7. Close the issue: bd close ${issue.id} --reason "<what you did>"
 8. Push: git pull --rebase && git push
@@ -924,7 +939,7 @@ IMPORTANT: If the previous session marked this issue blocked with a diagnostic,
 
 Otherwise, complete the workflow:
 - Finish any remaining implementation
-- Run tests to verify
+- Run the tests that step 5 of your first instructions describes: the issue's own test scope if it states one, otherwise the focused tests for what you changed plus the static check, and not the full suite unless the issue asks for it
 - Commit changes referencing the issue ID
 - Close the issue with bd close
 - Push with: git pull --rebase && git push
@@ -957,6 +972,42 @@ function shouldRotateSession(peakContext, contextWindow, fraction = ROTATE_FRACT
     const window = contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW;
     return peakContext >= fraction * window;
 }
+/**
+ * How many sessions in a row may end without doing any work before the loop
+ * stops. Fixed, with no flag: no caller needs a different number. A claim that
+ * fails before a session starts counts as one such session (boop-rfof).
+ *
+ * A claim that cannot start work costs four sessions at the default
+ * --resume-limit (the first run plus three resumes), so five means the loop has
+ * claimed an issue a second time and that claim did not start either. In the
+ * incident this rule comes from (boop-to45.2), expired credentials produced
+ * 1,543 such sessions in 64 minutes, each one turn long and over within a second.
+ */
+exports.NO_WORK_SESSION_LIMIT = 5;
+/**
+ * Whether a session did any work, which here means it called at least one tool.
+ * A session cannot read a file, claim its issue or run a command without one,
+ * so a session with no tool calls started nothing, whatever the reason: expired
+ * or missing credentials, an upstream outage, a `claude` binary that is not
+ * there. The test deliberately ignores how long the session lasted and what its
+ * error said, because an outage that retries for a minute before giving up is
+ * the same fault as a credential check that fails at once.
+ */
+function sessionDidWork(run) {
+    return (run.toolCalls ?? 0) > 0;
+}
+/**
+ * Split a session's stream-json output into complete lines. A stdout chunk ends
+ * wherever the pipe buffer happened to fill, so the last piece of a chunk may be
+ * the first part of a line whose remainder arrives in the next chunk: it comes
+ * back as `rest`, for the caller to pass in as `carry` with the next chunk and
+ * to flush when the stream closes. Pure so a test can feed it a line cut in two.
+ */
+function splitStreamLines(carry, chunk) {
+    const pieces = (carry + chunk).split('\n');
+    const rest = pieces.pop() ?? '';
+    return { lines: pieces.filter(Boolean), rest };
+}
 function runClaude(prompt, opts, logFile, readableLogFile) {
     return new Promise((resolve) => {
         const args = [
@@ -980,7 +1031,7 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
         const claudeBin = findClaudeBinary();
         if (!claudeBin) {
             console.error('\x1b[31m[bd-loop]\x1b[0m claude binary not found');
-            resolve({ exitCode: 1, limitHit: false });
+            resolve({ exitCode: 1, limitHit: false, toolCalls: 0, finalText: 'claude binary not found' });
             return;
         }
         const logStream = fs.createWriteStream(logFile, { flags: 'a' });
@@ -1006,11 +1057,20 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
         // the run drives session rotation; contextWindow comes from the result.
         let peakContext = 0;
         let contextWindow;
+        // What the no-work rule in runLoop needs from this session: whether it called
+        // any tool, and what it said last.
+        let toolCalls = 0;
+        let lastAssistantText = '';
+        let resultText = '';
+        let lastStderrLine = '';
         child.stdin.write(prompt);
         child.stdin.end();
-        child.stdout.on('data', (chunk) => {
-            logStream.write(chunk);
-            const lines = chunk.toString().split('\n').filter(Boolean);
+        // A line longer than the pipe buffer arrives in several chunks, so the
+        // unterminated tail of each chunk waits here for the rest of its line. The
+        // decoder does the same for a multi-byte character cut between chunks.
+        const stdoutDecoder = new string_decoder_1.StringDecoder('utf8');
+        let stdoutTail = '';
+        const readLines = (lines) => {
             for (const line of lines) {
                 try {
                     const msg = JSON.parse(line);
@@ -1024,6 +1084,7 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
                             .map((c) => c.text);
                         if (texts.length > 0) {
                             const textBlob = texts.join('');
+                            lastAssistantText = textBlob;
                             if (isStandaloneUsageLimitMessage(textBlob)) {
                                 limitHit = true;
                             }
@@ -1036,6 +1097,7 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
                         const tools = (msg.message?.content || [])
                             .filter((c) => c.type === 'tool_use')
                             .map((c) => `${c.name} ${JSON.stringify(c.input).substring(0, 80)}`);
+                        toolCalls += tools.length;
                         for (const t of tools) {
                             console.log(`\x1b[32m[bd-loop]\x1b[0m     🔧 ${t}`);
                             if (readableStream) {
@@ -1044,7 +1106,7 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
                         }
                     }
                     else if (msg.type === 'result') {
-                        const resultText = typeof msg.result === 'string' ? msg.result : '';
+                        resultText = typeof msg.result === 'string' ? msg.result : '';
                         if ((msg.is_error || msg.subtype === 'error') && isUsageLimitText(resultText)) {
                             limitHit = true;
                         }
@@ -1073,22 +1135,38 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
                     }
                 }
             }
+        };
+        child.stdout.on('data', (chunk) => {
+            logStream.write(chunk);
+            const split = splitStreamLines(stdoutTail, stdoutDecoder.write(chunk));
+            stdoutTail = split.rest;
+            readLines(split.lines);
         });
         child.stderr.on('data', (chunk) => {
             logStream.write(chunk);
+            const stderrLines = chunk.toString().split('\n').filter((l) => l.trim());
+            if (stderrLines.length > 0)
+                lastStderrLine = stderrLines[stderrLines.length - 1];
             if (isStandaloneUsageLimitMessage(chunk.toString())) {
                 limitHit = true;
             }
         });
         child.on('close', (code) => {
+            // Output that ended without a newline is still a line.
+            const lastLine = stdoutTail + stdoutDecoder.end();
+            stdoutTail = '';
+            if (lastLine)
+                readLines([lastLine]);
             logStream.end();
             if (readableStream)
                 readableStream.end();
-            resolve({ exitCode: code ?? 1, limitHit, peakContext, contextWindow });
+            const finalText = (resultText || lastAssistantText || lastStderrLine).trim() || undefined;
+            resolve({ exitCode: code ?? 1, limitHit, peakContext, contextWindow, toolCalls, finalText });
         });
     });
 }
 async function processIssue(issue, opts) {
+    const runClaude = opts.runClaudeFn;
     const sessionId = opts.session?.id ?? (0, crypto_1.randomUUID)();
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').substring(0, 19);
     const logFile = path.join(opts.logDir, `${issue.id}_${timestamp}.log`);
@@ -1109,12 +1187,16 @@ async function processIssue(issue, opts) {
         }
         catch {
             try {
-                (0, child_process_1.execSync)(`git checkout ${branchName} 2>/dev/null`, { encoding: 'utf8', cwd: opts.cwd });
+                (0, child_process_1.execSync)(`git checkout ${branchName}`, { encoding: 'utf8', cwd: opts.cwd, stdio: 'pipe' });
                 console.log(`\x1b[33m[bd-loop]\x1b[0m   Branch ${branchName} exists, checked out`);
             }
-            catch {
-                console.error(`\x1b[31m[bd-loop]\x1b[0m   Failed to create/checkout branch`);
-                return { issueId: issue.id, closed: false, resumes: 0, logFile, limitHit: false };
+            catch (e) {
+                // The issue stays open and ready, so this claim counts as an attempt
+                // that did no work; otherwise the loop would claim it again indefinitely.
+                const gitError = String(e.stderr || e.message).trim();
+                const claimFailure = `Failed to create/checkout branch ${branchName}: ${gitError}`;
+                console.error(`\x1b[31m[bd-loop]\x1b[0m   ${claimFailure}`);
+                return { issueId: issue.id, closed: false, resumes: 0, logFile, limitHit: false, noWorkStreak: opts.noWorkStreak + 1, claimFailure };
             }
         }
     }
@@ -1134,12 +1216,21 @@ async function processIssue(issue, opts) {
     let anyLimitHit = initialRun.limitHit;
     let peakContext = initialRun.peakContext ?? 0;
     let contextWindow = initialRun.contextWindow;
+    // Any session that does work starts the count again, so an issue that takes
+    // many working sessions never approaches the limit.
+    let noWorkStreak = sessionDidWork(initialRun) ? 0 : opts.noWorkStreak + 1;
+    let lastSessionText = initialRun.finalText;
     if (initialRun.limitHit) {
         console.error('\x1b[31m[bd-loop]\x1b[0m   Claude usage limit reached; stopping retries for this issue');
     }
     // Resume loop
     let resumeCount = 0;
     while (resumeCount < opts.resumeLimit && !initialRun.limitHit) {
+        // Enough sessions in a row have done no work. Another resume would be one
+        // more of the same, so hand back to runLoop, which stops the loop.
+        if (noWorkStreak >= exports.NO_WORK_SESSION_LIMIT) {
+            break;
+        }
         if (isIssueClosed(issue.id)) {
             console.log(`\x1b[32m[bd-loop]\x1b[0m   ✅ Issue ${issue.id} closed successfully`);
             break;
@@ -1168,6 +1259,8 @@ async function processIssue(issue, opts) {
             peakContext = resumeRun.peakContext;
         if (resumeRun.contextWindow)
             contextWindow = resumeRun.contextWindow;
+        noWorkStreak = sessionDidWork(resumeRun) ? 0 : noWorkStreak + 1;
+        lastSessionText = resumeRun.finalText;
         if (resumeRun.limitHit) {
             anyLimitHit = true;
             console.error('\x1b[31m[bd-loop]\x1b[0m   Claude usage limit reached during resume; stopping retries for this issue');
@@ -1179,7 +1272,7 @@ async function processIssue(issue, opts) {
         console.log(`\x1b[32m[bd-loop]\x1b[0m   ✅ Done: ${issue.id}`);
     }
     else {
-        console.error(`\x1b[31m[bd-loop]\x1b[0m   ⚠️  Issue ${issue.id} not closed after ${opts.resumeLimit} resume attempts`);
+        console.error(`\x1b[31m[bd-loop]\x1b[0m   ⚠️  Issue ${issue.id} not closed after ${resumeCount} resume attempts`);
         console.error(`\x1b[31m[bd-loop]\x1b[0m   Check log: ${logFile}`);
     }
     if (originalBranch) {
@@ -1190,12 +1283,12 @@ async function processIssue(issue, opts) {
             // Best effort
         }
     }
-    return { issueId: issue.id, closed, resumes: resumeCount, logFile, limitHit: anyLimitHit, sessionId, peakContext, contextWindow };
+    return { issueId: issue.id, closed, resumes: resumeCount, logFile, limitHit: anyLimitHit, sessionId, peakContext, contextWindow, noWorkStreak, lastSessionText };
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function runLoop(options) {
+async function runLoop(options, deps) {
     let prefix = options.prefix;
     const work = options.work;
     const flow = options.flow;
@@ -1386,6 +1479,34 @@ async function runLoop(options) {
     // Issue id at each session START (the first entry is the initial session, not a
     // rotation). Actual rotations are everything after the first — see the summary.
     const sessionStarts = [];
+    // Attempts in a row that did no work, counted across claims and across
+    // issues: sessions that called no tool, and claims that failed before a
+    // session started. See NO_WORK_SESSION_LIMIT.
+    let noWorkStreak = 0;
+    // An issue left open is claimed again on the next pass, and --resume-limit
+    // only bounds one claim, so without this stop a loop whose claims cannot
+    // start work would claim the same issue indefinitely (boop-to45.2). It
+    // applies under --poll as well: waiting does not repair a credential.
+    // Returns whether the loop has to stop.
+    const stopIfWorkIsNotStarting = (last) => {
+        if (noWorkStreak < exports.NO_WORK_SESSION_LIMIT)
+            return false;
+        console.error(`\x1b[31m[bd-loop]\x1b[0m Stopping: the last ${noWorkStreak} attempts in a row did no work ` +
+            `(a session that ended without calling a single tool, or a claim that failed before a session started), ` +
+            `so work is not starting. This is NOT a clean finish.`);
+        if (last.claimFailure) {
+            console.error(`\x1b[31m[bd-loop]\x1b[0m The last claim, of ${last.issueId}, failed before a session started: ${last.claimFailure}`);
+        }
+        else {
+            const said = last.lastSessionText
+                ? last.lastSessionText.replace(/\s+/gu, ' ').substring(0, 500)
+                : '(nothing: it produced no output)';
+            console.error(`\x1b[31m[bd-loop]\x1b[0m The last session, on ${last.issueId}, said: ${said}`);
+        }
+        console.error(`\x1b[31m[bd-loop]\x1b[0m Fix that cause and start the loop again.${last.logFile ? ` Log: ${last.logFile}` : ''}`);
+        process.exitCode = 1;
+        return true;
+    };
     while (true) {
         let nextId = null;
         if (prefix) {
@@ -1470,7 +1591,12 @@ async function runLoop(options) {
         // Process the issue
         const issue = getIssueInfo(nextId);
         if (!issue) {
-            console.error(`\x1b[31m[bd-loop]\x1b[0m   Failed to get issue details for ${nextId}`);
+            const claimFailure = `Failed to get issue details for ${nextId}`;
+            console.error(`\x1b[31m[bd-loop]\x1b[0m   ${claimFailure}`);
+            // The issue is still ready, so the next pass finds it again at once.
+            noWorkStreak++;
+            if (stopIfWorkIsNotStarting({ issueId: nextId, claimFailure }))
+                break;
             continue;
         }
         // Decide the session this issue runs under. Reuse a healthy carried session;
@@ -1502,8 +1628,11 @@ async function runLoop(options) {
             logDir,
             cwd: loopCwd,
             session,
+            noWorkStreak,
+            runClaudeFn: deps?.runClaudeFn || runClaude,
         });
         results.push(result);
+        noWorkStreak = result.noWorkStreak;
         if (result.closed)
             totalClosed++;
         // Fold this issue's observed context back into the carried session so the next
@@ -1521,6 +1650,9 @@ async function runLoop(options) {
             console.error('\x1b[31m[bd-loop]\x1b[0m   Credit/usage limit hit — stopping loop');
             break;
         }
+        // A failed claim wrote no session log, so there is none to point at.
+        if (stopIfWorkIsNotStarting(result.claimFailure ? { ...result, logFile: undefined } : result))
+            break;
     }
     // Always-worktree: leave the worktree and branch in place for the operator to
     // review and merge by hand (manual merge is the v1 contract). No checkout-back —

package/docs/loop.md

@@ -29,6 +29,8 @@ Without `--run`, the command shows what it would do without executing anything.
 
 Each Claude session gets a full prompt with issue details and instructions to work autonomously through the complete workflow: claim, implement, test, commit, close, and push.
 
+The prompt does not tell a session to run the whole test suite. If the issue says which tests to run, the session runs those. Otherwise it runs the focused tests for the files it changed plus the project's static check, using the commands the `boop-testing-testing` skill and the `PROJECT.md` beside it give. The full suite runs only when an issue asks for it, which is normally the task that completes the branch, and again when `boop loop --merge` integrates the branch.
+
 ### Planning mode (`--work` + `--flow`)
 
 When `--work` and `--flow` are provided, boop loop runs a **plan-then-execute pipeline**:
@@ -120,7 +122,8 @@ Session logs are written to `labs/claude-runs/` in the project directory. Each i
 
 - **Dry-run by default** — nothing executes without `--run`
 - **Budget caps** — each issue is capped at `--budget` USD
-- **Resume limits** — prevents infinite retry loops (default: 3 attempts)
+- **Resume limits** — bounds the sessions spent on one claim of an issue (default: 3 resumes after the first run)
+- **Sessions that do no work stop the loop** — if five sessions in a row end without calling a single tool, the loop prints what the last one said and stops with exit code 1. This is what ends a run whose sessions cannot start, for example because the Claude Code credentials have expired or the API is down, which would otherwise claim the same issue again indefinitely. A claim that fails before any session starts counts as well: the issue's details could not be read, or with `--per-issue-branch` its branch could not be created or checked out. The loop then prints that failure in place of a session's last words. Any session that does work sets the count back to zero. The number is fixed.
 - **Permission skipping** — enabled by default for unattended operation; use `--no-skip-perms` to require approval for each tool call
 - **A failed queue read is never a clean finish** — if the loop cannot read the ready queue it says so and stops with exit code 1, rather than reporting "No more ready issues" and exiting 0. See [Reading the ready queue](#reading-the-ready-queue).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.6.18",
+  "version": "0.7.1",
   "description": "boop: the opinionated bootstrap for founder friendly, AI-first web apps - code plus agent skills, composable from day one.",
   "main": "dist/cli.js",
   "workspaces": [

package/profiles/web-app/reference/message-queue-patterns.ref.md

@@ -26,6 +26,29 @@ await MessageQueueService.publish('batch-ready', [message1, message2]);
 - **Error recovery**: If `publish()` catches an error (e.g., channel closed), it resets connection state and returns `false` — the next call will reconnect
 - **Shutdown**: The publish connection is tracked and closed by `close()` alongside the listener connection
 
+### Publishing to a queue that does not exist
+
+`publish()` does not declare the queue; only `listen()` does.
+A broker confirms a message that it cannot put in any queue and then discards it,
+so a publish to a name that no consumer has ever listened on returns `true` and the message is lost.
+
+Pass `{ mandatory: true }` as the third argument when the publisher cannot be sure the queue exists:
+when the name is composed at run time (for example with `targetPrefix`),
+or when the publisher can start before the consumer ever has.
+
+```typescript
+const queued = await MessageQueueService.publish('batch-ready', message, { targetPrefix, mandatory: true });
+if (!queued) {
+  // Not queued anywhere: record or report it.
+}
+```
+
+- The message is sent with the AMQP `mandatory` flag, and the broker returns it when no queue has the destination's name
+- `publish()` then logs `publish to "<queue>" was returned by the broker: no queue has that name` and returns `false`
+- The connection state is **not** reset in this case — the connection is healthy, and the next `publish()` reuses it
+- A queue that exists but has no consumer running still takes the message; the option reports a missing queue, not a missing worker
+- Without the option, `publish()` is unchanged
+
 ### Why persistent (not per-call)
 
 The original implementation opened a new AMQP connection for every `publish()` call, then immediately closed it. This works for infrequent publishing but fails under rapid iteration (e.g., `ch-export-push` publishing 177 batch-ready messages in seconds). CloudAMQP's shared plan rate-limits connection churn, causing `ECONNREFUSED` errors.
@@ -44,8 +67,12 @@ The original implementation opened a new AMQP connection for every `publish()` c
 
 - **Lazy init**: No connection is opened until the first `listen()` call
 - **Shared**: All listeners share the same connection; each gets its own channel with independent prefetch and consumer
-- **Auto-reconnect**: If the connection drops (`error` or `close` event), the cached reference is cleared and the next `listen()` call opens a fresh connection
-- **Shutdown**: The listener connection is closed by `close()` alongside the publish connection
+- **Auto-reconnect**: If the connection drops (`error` or `close` event), the service opens one new connection and attaches every consumer again — same queue, options and handler — without another `listen()` call. While the broker is unreachable it retries, waiting 1s and doubling up to 30s
+- **Logging**: The drop is logged at `warn` (`listener connection lost … re-attaching N consumer(s)`), each failed attempt at `error`, and each consumer that is consuming again at `info` (`re-attached consumer on "<queue>"`)
+- **Redelivery**: A message that was delivered but not yet ACKed when the connection dropped is delivered again by the broker, so a handler can see the same message twice. Handlers must tolerate processing a message a second time. This repeat does not count as a retry (see [Retry & Dead Letter Queue](#retry--dead-letter-queue-dlq)). An ACK or NACK for the first delivery — including a deferred one in manual-ACK mode — cannot be sent on the closed channel; the service logs it at `warn` and does not throw
+- **Cancelled consumers**: A `Subscription` that was cancelled is not attached again. `cancel()` after a re-attach stops the consumer that is current at that moment, and `consumerTag` reports the new broker-assigned tag
+- **Closed channel**: Only the connection is watched. A single consumer's channel that the broker closes while the connection stays up is not re-attached
+- **Shutdown**: The listener connection is closed by `close()` alongside the publish connection. `close()` ends consumption for good and never starts a re-attach
 
 ### Why shared (not per-queue)
 
@@ -61,10 +88,11 @@ The `MessageQueueService.listen()` function supports two modes controlled by `op
 MessageQueueService.listen('queue-name', handler);
 ```
 
-- Handler signature: `async handler(msg) → boolean`
+- Handler signature: `async handler(msg, delivery) → boolean`
 - Returns `true` → message ACKed immediately
-- Returns `false` → sent to retry queue with exponential backoff
-- Throws → NACKed to DLQ after max retries
+- Returns `false` → the message is delivered again after a backoff, and moves to the DLQ when its last attempt fails
+- Throws → the same as returning `false`, and the error is logged
+- `delivery` is `{ retryCount, lastAttempt }` (the `Delivery` type exported by `@boopkit/cap-background-jobs`); a handler that takes only `msg` keeps working
 - **Use case**: Simple request-response consumers (e.g., entity replication, long running jobs)
 
 ### Manual-ACK Mode
@@ -76,7 +104,8 @@ MessageQueueService.listen('queue-name', handler, { manualAck: true, prefetch: N
 - Handler signature: `async handler(msg, ack, nack)`
 - `ack()` and `nack()` are guarded — only the first call takes effect
 - Handler is responsible for calling `ack()` or `nack()` (can be deferred)
-- If handler throws without settling → message moved to DLQ
+- `nack()`, a throw without settling, or resolving without settling → the message is delivered again after a backoff, and moves to the DLQ when its last attempt fails
+- The handler does not receive a `Delivery`
 - **Use case**: Buffered/batch consumers where ACK is deferred until a batch operation completes
 
 ## Retry & Dead Letter Queue (DLQ)
@@ -90,10 +119,34 @@ Every queue gets automatic retry and DLQ infrastructure:
 | `{name}.failed` | DLQ — messages that exceed max retries land here |
 
 **Retry behavior**:
-- Exponential backoff: `min(BASE * 2^retryCount, MAX)` — default BASE=4s, MAX=60s
-- Max retries: 5 (configurable via `MAX_MESSAGE_RETRIES` env var)
+- A failed message is ACKed and a copy is published to the retry queue's exchange (`{name}.retry.exchange`) with a TTL. When the TTL expires the broker dead-letters it to the main exchange, which delivers it to the main queue, and the handler is called again
+- Exponential backoff: `min(BASE * 2^retryCount, MAX)` — BASE=4s, MAX=60s, so the waits are 4s, 8s, 16s, 32s, then 60s
+- Max retries: 5 (configurable via `MAX_MESSAGE_RETRIES` env var). With the default, a handler that keeps failing is called six times: the first delivery and five retries
 - Retry count tracked in `x-retry-count` message header
-- After max retries → NACK without requeue → routed to DLQ via dead letter exchange
+- When the last attempt fails → the message is published to the `{name}.failed` queue and the delivery is ACKed
+
+**Handlers must be safe to run more than once for one message.** Every failure leads to another call with the same payload, so a side effect the handler completed before it failed (an email sent, a row inserted) happens again unless the handler checks first. Make the work idempotent: check whether it was already done, or upsert on an id carried in the payload.
+
+Versions of `@boopkit/cap-background-jobs` up to 0.4.3 did not redeliver: the broker discarded a failed message when its retry TTL expired, and nothing reached the DLQ. A project upgrading from one of those versions has handlers that have never been called twice for a message, so review each one.
+
+**The last attempt.** An auto-ACK handler's second argument tells it which delivery it is handling:
+
+| Field | Meaning |
+|-------|---------|
+| `retryCount` | How many times the message has already been retried; `0` on its first delivery |
+| `lastAttempt` | `true` on the delivery whose failure moves the message to the DLQ, `false` while retries remain |
+
+Use `lastAttempt` for something that should happen once per failed message and not once per attempt:
+
+```typescript
+import type { Delivery } from '@boopkit/cap-background-jobs';
+
+async function onMessage(msg: unknown, delivery: Delivery): Promise<boolean> {
+  const ok = await recordInboundEmail(msg);
+  if (!ok && delivery.lastAttempt) await notifyAdmin('an inbound email failed on every attempt', msg);
+  return ok;
+}
+```
 
 ## Buffered Batch ACK Pattern
 

package/src/templates/kernel/AGENTS.md.hbs

@@ -23,5 +23,5 @@ Read [reference/boop-guide.ref.md](reference/boop-guide.ref.md) to understand ho
 - `skills/` — process skills for agents (each skill is a folder with a `SKILL.md`); also linked from `.claude/skills/` for Claude Code's built-in skill discovery
 - `reference/` — architecture and coding standards ("what exists now")
 - `specs/` — design docs and specifications ("future state")
-- `tests/` — `npm test` (Jest)
+- `tests/` — tests. Before you run or write one, read [skills/boop-testing-testing/SKILL.md](skills/boop-testing-testing/SKILL.md) and [skills/boop-testing-testing/PROJECT.md](skills/boop-testing-testing/PROJECT.md): they say which tests a change runs, when the whole suite runs, and this project's commands for both
 - `.boop/` — project manifest (managed by boop)