@boopkit/cli 0.4.1 → 0.6.0

package/dist/commands/loop.js

@@ -33,18 +33,318 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESUME_PROMPT = exports.DEFAULT_BUDGET_USD = void 0;
+exports.assertDoltServerMode = assertDoltServerMode;
+exports.discoverDoltServer = discoverDoltServer;
+exports.createWorktree = createWorktree;
+exports.writeWorktreeMetadata = writeWorktreeMetadata;
 exports.buildPlanningPrompt = buildPlanningPrompt;
 exports.planWork = planWork;
 exports.findFallbackFeature = findFallbackFeature;
 exports.extractFeatureId = extractFeatureId;
 exports.isUsageLimitText = isUsageLimitText;
 exports.isStandaloneUsageLimitMessage = isStandaloneUsageLimitMessage;
+exports.resolveModel = resolveModel;
+exports.shouldResumeUnclosedIssue = shouldResumeUnclosedIssue;
 exports.isIssueInScope = isIssueInScope;
+exports.isClaimableReadyIssue = isClaimableReadyIssue;
+exports.shouldCloseFeatureRoot = shouldCloseFeatureRoot;
+exports.getMatchingReadyIssues = getMatchingReadyIssues;
 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");
+/**
+ * Hard requirement: beads must run in Dolt server mode so concurrent worktrees
+ * share one issue DB over TCP. Reads `.beads/metadata.json` and throws an
+ * actionable error on embedded/missing — call before any `bd` work.
+ */
+function assertDoltServerMode(projectDir, deps) {
+    const existsSyncFn = deps?.existsSyncFn || fs.existsSync;
+    const readFileFn = deps?.readFileFn || ((p, enc) => fs.readFileSync(p, enc));
+    const metaPath = path.join(projectDir, '.beads', 'metadata.json');
+    const fix = 'Migrate beads to Dolt server mode before running the loop; see skills/boop-dolt-recovery/SKILL.md';
+    if (!existsSyncFn(metaPath)) {
+        throw new Error(`beads metadata not found at ${metaPath}. The loop requires Dolt server mode for concurrent worktrees. ${fix}`);
+    }
+    let mode;
+    try {
+        const meta = JSON.parse(readFileFn(metaPath, 'utf8'));
+        mode = meta.dolt_mode;
+    }
+    catch (e) {
+        throw new Error(`Failed to parse ${metaPath}: ${e.message}. ${fix}`);
+    }
+    if (mode !== 'server') {
+        throw new Error(`beads is in dolt_mode="${mode ?? 'unset'}" (read from ${metaPath}); the loop requires dolt_mode="server" so concurrent worktrees share one issue DB. ${fix}`);
+    }
+}
+/**
+ * Discover the running shared Dolt server's port from `.beads/dolt-server.port`.
+ * Worktrees never start their own server — they reuse this one over TCP.
+ * Returns null when no port file is present (caller errors clearly). Liveness
+ * (pid still running) is best-effort and never blocks discovery.
+ */
+function discoverDoltServer(projectDir, deps) {
+    const existsSyncFn = deps?.existsSyncFn || fs.existsSync;
+    const readFileFn = deps?.readFileFn || ((p, enc) => fs.readFileSync(p, enc));
+    const isPidAliveFn = deps?.isPidAliveFn ||
+        ((pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+    const portPath = path.join(projectDir, '.beads', 'dolt-server.port');
+    if (!existsSyncFn(portPath)) {
+        return null;
+    }
+    const port = parseInt(readFileFn(portPath, 'utf8').trim(), 10);
+    if (!Number.isFinite(port) || port <= 0) {
+        return null;
+    }
+    // Best-effort liveness: read pid file and probe; never throws/blocks.
+    let pid;
+    let alive;
+    const pidPath = path.join(projectDir, '.beads', 'dolt-server.pid');
+    if (existsSyncFn(pidPath)) {
+        const parsed = parseInt(readFileFn(pidPath, 'utf8').trim(), 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            pid = parsed;
+            alive = isPidAliveFn(parsed);
+        }
+    }
+    return { port, pid, alive };
+}
+/**
+ * Create (or reuse) the loop's own git worktree at `../boop-<scope>` on branch
+ * `work/<scope>`, then pre-warm `npm install --prefer-offline`. This is what
+ * makes N loops run concurrently without colliding — each gets its own tree and
+ * branch; main is never checked out.
+ *
+ * Collision (Decision #4): if a worktree already exists at the path on the same
+ * branch, reuse it (and skip install if node_modules is present); if the path is
+ * occupied by something else, throw a clear error rather than silently suffixing.
+ */
+function createWorktree(scope, mode, projectDir, deps) {
+    const execSyncFn = deps?.execSyncFn ||
+        ((cmd, o) => (0, child_process_1.execSync)(cmd, o));
+    const existsSyncFn = deps?.existsSyncFn || fs.existsSync;
+    const copyFileFn = deps?.copyFileFn || ((src, dest) => fs.copyFileSync(src, dest));
+    const readdirFn = deps?.readdirFn || ((p) => fs.readdirSync(p));
+    const readFileFn = deps?.readFileFn || ((p) => fs.readFileSync(p, 'utf8'));
+    const appendFileFn = deps?.appendFileFn || ((p, data) => fs.appendFileSync(p, data));
+    const branch = `work/${scope}`;
+    const worktreePath = path.resolve(projectDir, '..', `boop-${scope}`);
+    const ctx = { path: worktreePath, branch, scope, mode };
+    // A fresh worktree checks out its own (tracked) `.beads/` but NOT the gitignored
+    // runtime files dolt-server.port/pid. Without them, `bd` inside the worktree
+    // auto-starts a ROGUE Dolt server on a different port and can't see the issue DB.
+    // Propagate the shared server's discovery files so the worktree reuses it.
+    // (Verified in Task 1.7 — see specs/parallel-worktree-development-audit.md.)
+    const propagateServerFiles = () => {
+        for (const file of ['dolt-server.port', 'dolt-server.pid']) {
+            const src = path.join(projectDir, '.beads', file);
+            const dest = path.join(worktreePath, '.beads', file);
+            if (existsSyncFn(src) && existsSyncFn(path.join(worktreePath, '.beads'))) {
+                try {
+                    copyFileFn(src, dest);
+                }
+                catch {
+                    // Best-effort; discovery already validated the shared server in runLoop.
+                }
+            }
+        }
+    };
+    // Gitignored runtime config (`.env` and friends) lives only in the main working
+    // tree — `git worktree add` checks out tracked files only, so a fresh worktree
+    // would start with no environment and the agent's app/tests would fail. Seed
+    // copies of root-level `.env*` files. Copy (not symlink) to keep worktrees
+    // isolated, matching the spec's "each worktree is a full working copy (own
+    // node_modules, own .env)". Don't clobber a file the agent may already have
+    // customized in a reused worktree. (boop-bf3)
+    const propagateConfigFiles = () => {
+        let entries;
+        try {
+            entries = readdirFn(projectDir);
+        }
+        catch {
+            return; // best-effort — a missing/unreadable project dir shouldn't abort setup
+        }
+        for (const name of entries) {
+            if (name !== '.env' && !name.startsWith('.env.'))
+                continue;
+            const src = path.join(projectDir, name);
+            const dest = path.join(worktreePath, name);
+            try {
+                if (existsSyncFn(src) && !existsSyncFn(dest)) {
+                    copyFileFn(src, dest);
+                }
+            }
+            catch {
+                // Best-effort; one unreadable config file shouldn't abort worktree setup.
+            }
+        }
+    };
+    // `.boop-worktree.json` is per-worktree runtime state (scope/branch/in-scope
+    // issues), not source. It must NEVER be tracked: if a closeout `git add` sweeps
+    // it into a commit, sibling worktree branches inherit a stale copy, and a later
+    // `git stash`/`git pull --rebase` can silently revert THIS worktree's metadata
+    // to another scope (the wf-bir→wf-ayn regression — boop-g0l). Register the
+    // ignore in the repo's local git exclude (resolved per-worktree via
+    // `git rev-parse --git-path info/exclude`) rather than the tracked `.gitignore`,
+    // so adding the rule never itself becomes an uncommitted tracked change that
+    // blocks the closeout's `git pull --rebase`. Idempotent and best-effort.
+    const ensureMetadataIgnored = () => {
+        try {
+            const raw = execSyncFn('git rev-parse --git-path info/exclude', {
+                encoding: 'utf8',
+                cwd: worktreePath,
+            });
+            const rel = (raw || '').trim();
+            if (!rel)
+                return;
+            const excludePath = path.isAbsolute(rel) ? rel : path.join(worktreePath, rel);
+            let current = '';
+            try {
+                current = readFileFn(excludePath);
+            }
+            catch {
+                // Exclude file may not exist yet — treat as empty; append will create it.
+            }
+            const already = current.split('\n').some((l) => l.trim() === '.boop-worktree.json');
+            if (already)
+                return;
+            const sep = current.length > 0 && !current.endsWith('\n') ? '\n' : '';
+            appendFileFn(excludePath, `${sep}.boop-worktree.json\n`);
+        }
+        catch {
+            // Best-effort: worst case the metadata file shows as untracked — still safer
+            // than the pre-fix tracked state. Never abort worktree setup over this.
+        }
+    };
+    // Is this path already a registered worktree? Parse `git worktree list --porcelain`.
+    let existingBranch;
+    let pathAlreadyWorktree = false;
+    try {
+        const raw = execSyncFn('git worktree list --porcelain', { encoding: 'utf8', cwd: projectDir });
+        const blocks = raw.split('\n\n');
+        for (const block of blocks) {
+            const lines = block.split('\n');
+            const wtLine = lines.find((l) => l.startsWith('worktree '));
+            if (!wtLine)
+                continue;
+            const wtPath = path.resolve(wtLine.slice('worktree '.length).trim());
+            if (wtPath === worktreePath) {
+                pathAlreadyWorktree = true;
+                const brLine = lines.find((l) => l.startsWith('branch '));
+                if (brLine) {
+                    // refs/heads/work/<scope> → work/<scope>
+                    existingBranch = brLine.slice('branch '.length).trim().replace(/^refs\/heads\//, '');
+                }
+            }
+        }
+    }
+    catch {
+        // No git / no worktrees yet — proceed to create.
+    }
+    if (pathAlreadyWorktree) {
+        if (existingBranch && existingBranch !== branch) {
+            throw new Error(`Worktree at ${worktreePath} is on branch "${existingBranch}", not the expected "${branch}". ` +
+                `Remove it (git worktree remove ${worktreePath}) or choose a different scope.`);
+        }
+        // Seed gitignored runtime config before any (re)install/bd work.
+        propagateConfigFiles();
+        // Reuse: only install if dependencies are missing.
+        if (!existsSyncFn(path.join(worktreePath, 'node_modules'))) {
+            execSyncFn('npm install --prefer-offline', { encoding: 'utf8', cwd: worktreePath });
+        }
+        propagateServerFiles();
+        ensureMetadataIgnored();
+        return ctx;
+    }
+    if (existsSyncFn(worktreePath)) {
+        throw new Error(`Path ${worktreePath} already exists but is not a registered git worktree. ` +
+            `Remove it or choose a different scope before running the loop.`);
+    }
+    // Does the branch already exist? If so, attach the worktree to it; else create it.
+    let branchExists = false;
+    try {
+        execSyncFn(`git rev-parse --verify --quiet refs/heads/${branch}`, { encoding: 'utf8', cwd: projectDir });
+        branchExists = true;
+    }
+    catch {
+        branchExists = false;
+    }
+    if (branchExists) {
+        execSyncFn(`git worktree add ${worktreePath} ${branch}`, { encoding: 'utf8', cwd: projectDir });
+    }
+    else {
+        execSyncFn(`git worktree add ${worktreePath} -b ${branch}`, { encoding: 'utf8', cwd: projectDir });
+    }
+    // Point the worktree's bd at the shared server before any bd work happens.
+    propagateServerFiles();
+    // Seed gitignored runtime config (`.env` etc.) that `git worktree add` doesn't
+    // check out, so the app/tests have their environment before install/session. (boop-bf3)
+    propagateConfigFiles();
+    // Pre-warm dependencies so the agent doesn't burn budget on a deterministic step.
+    execSyncFn('npm install --prefer-offline', { encoding: 'utf8', cwd: worktreePath });
+    // Ignore the metadata file before it is ever written (writeWorktreeMetadata runs
+    // next in runLoop), so no later `git add` can track it.
+    ensureMetadataIgnored();
+    return ctx;
+}
+/**
+ * Write `.boop-worktree.json` into the worktree root. This is the contract
+ * Slice 2 (`boop loop --merge`) reads — `mode` drives its readiness query.
+ */
+function writeWorktreeMetadata(ctx, meta, deps) {
+    const writeFileFn = deps?.writeFileFn || ((p, data) => fs.writeFileSync(p, data));
+    const data = {
+        version: 1,
+        mode: ctx.mode,
+        scope: ctx.scope,
+        branch: ctx.branch,
+        worktreePath: ctx.path,
+    };
+    if (ctx.mode === 'work-flow') {
+        if (meta.workPath)
+            data.workPath = meta.workPath;
+        if (meta.flowPath)
+            data.flowPath = meta.flowPath;
+    }
+    data.startTime = meta.startTime;
+    data.boopVersion = meta.boopVersion;
+    if (meta.operator)
+        data.operator = meta.operator;
+    if (meta.budget)
+        data.budget = meta.budget;
+    if (meta.model)
+        data.model = meta.model;
+    writeFileFn(path.join(ctx.path, '.boop-worktree.json'), JSON.stringify(data, null, 2) + '\n');
+    return data;
+}
+function getBoopVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8'));
+        return pkg.version || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function getGitUserName(projectDir) {
+    try {
+        return (0, child_process_1.execSync)('git config user.name', { encoding: 'utf8', cwd: projectDir }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function buildPlanningPrompt(workContent, flowContent, prefix) {
     let prompt = `You are setting up work for a development project.
 
@@ -235,6 +535,28 @@ function findClaudeBinary() {
         return null;
     }
 }
+/**
+ * Resolve the model for a loop run. Precedence: an explicit `--model` flag, then
+ * the `ANTHROPIC_MODEL` environment variable, then the built-in default. The env
+ * fallback is what lets a nested `boop loop` (spawned by a Claude session that
+ * the parent loop launched with ANTHROPIC_MODEL set) inherit the same model
+ * instead of silently dropping to the default. Keep the default (claude-opus-4-8)
+ * in sync with the `--model` help text in cli.ts.
+ */
+function resolveModel(optionModel, env = process.env) {
+    return optionModel || env.ANTHROPIC_MODEL || 'claude-opus-4-8';
+}
+/**
+ * Whether the loop should resume an issue that a session left open. A `blocked`
+ * issue was deliberately halted by the prior session because it judged it could
+ * not safely proceed — resuming just spends budget re-halting and risks the
+ * resume prompt being read as authorization to work past the block. Stop and
+ * surface it for the operator instead. Any other open status is genuinely
+ * unfinished work and is fine to resume.
+ */
+function shouldResumeUnclosedIssue(status) {
+    return status !== 'blocked';
+}
 function findNextIssue(prefix, includeFeatures) {
     const matching = getMatchingReadyIssues(prefix, includeFeatures);
     return matching.length > 0 ? matching[0].id : null;
@@ -265,9 +587,98 @@ function isIssueInScope(issue, prefix, getParentById) {
     }
     return false;
 }
-function getMatchingReadyIssues(prefix, includeFeatures) {
+/**
+ * A workflow-owned feature root is a feature-type issue that owns child tasks
+ * (the workflow steps: understand → plan → … → closeout). Once those children
+ * close, `bd ready` surfaces the feature root itself — but it is a *container*,
+ * not directly claimable work. Claiming it lets a worker session absorb
+ * punch-list fixes or whole workflow steps (the boop-qna / wishfleet-O7 bug).
+ *
+ * `hasChildren` is only consulted for feature-type issues, so non-features never
+ * pay the cost of the children lookup.
+ */
+function isClaimableReadyIssue(issue, hasChildren) {
+    if (issue.issue_type === 'feature' && hasChildren(issue.id)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Decide whether the loop should close a feature root itself, as a safety net,
+ * when its workflow chain has completed. The intended owner of this close is the
+ * closeout child task (see boop-feature-dev-workflow SKILL step 6), but if that
+ * task never closed the root — or no closeout task exists — the feature would be
+ * orphaned open forever once filtered from claimable work. Only close when the
+ * feature is still open and every child is closed.
+ */
+function shouldCloseFeatureRoot(feature, children) {
+    if (!feature || feature.issue_type !== 'feature') {
+        return false;
+    }
+    if (feature.status === 'closed') {
+        return false;
+    }
+    if (children.length === 0) {
+        return false;
+    }
+    return children.every((c) => c.status === 'closed');
+}
+function getIssueChildren(id) {
     try {
-        const raw = (0, child_process_1.execSync)('bd ready --json -n 20 2>/dev/null', { encoding: 'utf8' });
+        const raw = (0, child_process_1.execSync)(`bd show ${id} --children --json 2>/dev/null`, { encoding: 'utf8' });
+        const data = JSON.parse(raw);
+        const children = data[id];
+        return Array.isArray(children) ? children : [];
+    }
+    catch {
+        return [];
+    }
+}
+function issueHasChildren(id) {
+    return getIssueChildren(id).length > 0;
+}
+/**
+ * Safety net for spec-driven runs: when the workflow chain completes but the
+ * closeout child did not close the feature root, close it here so it is not
+ * orphaned open after the filter removes it from claimable work. Returns true if
+ * it closed the feature. Best-effort — failures are logged, not fatal.
+ */
+function closeCompletedFeatureRoot(featureId) {
+    const feature = getIssueInfoWithStatus(featureId);
+    const children = getIssueChildren(featureId);
+    if (!shouldCloseFeatureRoot(feature, children)) {
+        return false;
+    }
+    try {
+        (0, child_process_1.execSync)(`bd close ${featureId} --reason "bd-loop: closed feature root on workflow chain completion (all child tasks closed; closeout did not close it)" 2>/dev/null`, { encoding: 'utf8' });
+        console.log(`\x1b[32m[bd-loop]\x1b[0m Closed feature root ${featureId} — workflow chain complete (safety net; closeout had not closed it).`);
+        return true;
+    }
+    catch {
+        console.warn(`\x1b[33m[bd-loop]\x1b[0m Feature root ${featureId} chain is complete but \`bd close\` failed — close it manually.`);
+        return false;
+    }
+}
+function getIssueInfoWithStatus(id) {
+    try {
+        const raw = (0, child_process_1.execSync)(`bd show ${id} --json 2>/dev/null`, { encoding: 'utf8' });
+        const data = JSON.parse(raw);
+        const issue = data[0] || data;
+        return { status: issue.status || 'unknown', issue_type: issue.issue_type || 'task' };
+    }
+    catch {
+        return null;
+    }
+}
+function getMatchingReadyIssues(prefix, includeFeatures, deps) {
+    const execSyncFn = deps?.execSyncFn ||
+        ((cmd, opts) => (0, child_process_1.execSync)(cmd, opts));
+    try {
+        // -n 0 = unlimited. A bounded window (formerly -n 20) starves the scope
+        // filter below: with more than 20 ready issues globally, in-scope issues
+        // sorting outside the window are never seen and the loop exits with group
+        // work undone (boop-pra).
+        const raw = execSyncFn('bd ready --json -n 0 2>/dev/null', { encoding: 'utf8' });
         const issues = JSON.parse(raw);
         const typeFilter = includeFeatures
             ? (i) => i.issue_type !== 'epic'
@@ -284,9 +695,20 @@ function getMatchingReadyIssues(prefix, includeFeatures) {
             parentCache.set(id, parent);
             return parent;
         };
+        const childrenCache = new Map();
+        const hasChildren = (id) => {
+            const cached = childrenCache.get(id);
+            if (cached !== undefined) {
+                return cached;
+            }
+            const result = issueHasChildren(id);
+            childrenCache.set(id, result);
+            return result;
+        };
         return issues
             .filter(typeFilter)
-            .filter((issue) => isIssueInScope(issue, prefix, getParentById));
+            .filter((issue) => isIssueInScope(issue, prefix, getParentById))
+            .filter((issue) => isClaimableReadyIssue(issue, hasChildren));
     }
     catch {
         return [];
@@ -345,14 +767,32 @@ Do NOT pause for review. Work autonomously through to completion.
 If you discover additional issues during your work, file them with:
   bd create "Title" -d "description" --deps discovered-from:${issue.id}`;
 }
-const RESUME_PROMPT = `Approved. Continue working on this issue. Complete the full workflow:
+/**
+ * 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
+ * text so the documented default and the runtime fallback can't drift.
+ */
+exports.DEFAULT_BUDGET_USD = '25.00';
+/**
+ * Sent when resuming a session that ended without closing its issue. The opener
+ * must NOT read as operator authorization (the old "Approved. Continue..." text
+ * could be taken as permission to work past a block): an agent that marked the
+ * issue `blocked` made a deliberate safety call, and the block stands. The loop
+ * also skips resuming a `blocked` issue entirely (see shouldResumeUnclosedIssue)
+ * — this clause is the belt-and-suspenders for a block raised mid-resume.
+ */
+exports.RESUME_PROMPT = `The previous session ended without closing this issue. Reload the state and continue.
+
+IMPORTANT: 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.
+
+Otherwise, complete the workflow:
 - Finish any remaining implementation
 - Run tests to verify
 - Commit changes referencing the issue ID
 - Close the issue with bd close
 - Push with: git pull --rebase && git push
 
-Do NOT pause for review. Complete everything now.`;
+Do not pause for review of completed work. Complete everything now.`;
 function runClaude(prompt, opts, logFile, readableLogFile) {
     return new Promise((resolve) => {
         const args = [
@@ -383,7 +823,19 @@ function runClaude(prompt, opts, logFile, readableLogFile) {
         const readableStream = readableLogFile
             ? fs.createWriteStream(readableLogFile, { flags: 'a' })
             : null;
-        const child = (0, child_process_1.spawn)(claudeBin, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        // Propagate the chosen model beyond this session via the environment.
+        // `--model` (in args) sets this session; ANTHROPIC_MODEL additionally
+        // (a) reaches a nested `boop loop` — child processes inherit the env — so it
+        // doesn't reset to the default, and (b) is honored by any sub-agent whose
+        // definition opts into `model: inherit`. We deliberately do NOT set
+        // CLAUDE_CODE_SUBAGENT_MODEL: sub-agents keep their own declared model, so a
+        // deliberately-cheap agent (e.g. Explore on Haiku) stays cheap. The invoking
+        // agent can still override a sub-agent's model per-invocation when it needs
+        // to. See resolveModel().
+        const childEnv = opts.model
+            ? { ...process.env, ANTHROPIC_MODEL: opts.model }
+            : process.env;
+        const child = (0, child_process_1.spawn)(claudeBin, args, { cwd: opts.cwd, stdio: ['pipe', 'pipe', 'pipe'], env: childEnv });
         let limitHit = false;
         child.stdin.write(prompt);
         child.stdin.end();
@@ -462,17 +914,19 @@ async function processIssue(issue, opts) {
     fs.writeFileSync(readableLogFile, `=== ${issue.id}: ${issue.title} ===\nSession: ${sessionId}\nStarted: ${new Date().toISOString()}\n\n`);
     console.log(`\x1b[32m[bd-loop]\x1b[0m ━━━ \x1b[34m${issue.id}\x1b[0m (P${issue.priority} ${issue.issue_type}) ━━━`);
     console.log(`\x1b[32m[bd-loop]\x1b[0m   ${issue.title}`);
+    // Per-issue branches (when requested) are created *inside* the worktree cwd,
+    // so they nest under the loop's isolated tree rather than mutating main.
     let originalBranch;
     if (!opts.noBranch && opts.perIssueBranch) {
         const branchName = `fix/${issue.id}`;
-        originalBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf8' }).trim();
+        originalBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf8', cwd: opts.cwd }).trim();
         console.log(`\x1b[32m[bd-loop]\x1b[0m   Creating branch: ${branchName}`);
         try {
-            (0, child_process_1.execSync)(`git checkout -b ${branchName} 2>/dev/null`, { encoding: 'utf8' });
+            (0, child_process_1.execSync)(`git checkout -b ${branchName} 2>/dev/null`, { encoding: 'utf8', cwd: opts.cwd });
         }
         catch {
             try {
-                (0, child_process_1.execSync)(`git checkout ${branchName} 2>/dev/null`, { encoding: 'utf8' });
+                (0, child_process_1.execSync)(`git checkout ${branchName} 2>/dev/null`, { encoding: 'utf8', cwd: opts.cwd });
                 console.log(`\x1b[33m[bd-loop]\x1b[0m   Branch ${branchName} exists, checked out`);
             }
             catch {
@@ -490,6 +944,7 @@ async function processIssue(issue, opts) {
         skipPerms: opts.skipPerms,
         bare: opts.bare,
         sessionId,
+        cwd: opts.cwd,
     }, logFile, readableLogFile);
     let anyLimitHit = initialRun.limitHit;
     if (initialRun.limitHit) {
@@ -502,17 +957,25 @@ async function processIssue(issue, opts) {
             console.log(`\x1b[32m[bd-loop]\x1b[0m   ✅ Issue ${issue.id} closed successfully`);
             break;
         }
+        // Don't resume an issue the prior session deliberately blocked — that's a
+        // safety decision, not unfinished work. Resuming burns budget re-halting.
+        const statusInfo = getIssueInfoWithStatus(issue.id);
+        if (!shouldResumeUnclosedIssue(statusInfo?.status)) {
+            console.log(`\x1b[33m[bd-loop]\x1b[0m   ⛔ Issue ${issue.id} is marked '${statusInfo?.status}' — not resuming; operator review needed.`);
+            break;
+        }
         resumeCount++;
         console.log(`\x1b[33m[bd-loop]\x1b[0m   Issue not yet closed — resuming session (attempt ${resumeCount}/${opts.resumeLimit})`);
         console.log(`\x1b[32m[bd-loop]\x1b[0m   🔄 Resuming session ${sessionId.substring(0, 8)}...`);
         fs.appendFileSync(readableLogFile, `\n=== Resume attempt ${resumeCount} ===\nTime: ${new Date().toISOString()}\n\n`);
-        const resumeRun = await runClaude(RESUME_PROMPT, {
+        const resumeRun = await runClaude(exports.RESUME_PROMPT, {
             budget: opts.budget,
             model: opts.model,
             skipPerms: opts.skipPerms,
             bare: opts.bare,
             sessionId,
             resume: true,
+            cwd: opts.cwd,
         }, logFile, readableLogFile);
         if (resumeRun.limitHit) {
             anyLimitHit = true;
@@ -530,7 +993,7 @@ async function processIssue(issue, opts) {
     }
     if (originalBranch) {
         try {
-            (0, child_process_1.execSync)(`git checkout ${originalBranch} 2>/dev/null`);
+            (0, child_process_1.execSync)(`git checkout ${originalBranch} 2>/dev/null`, { cwd: opts.cwd });
         }
         catch {
             // Best effort
@@ -559,6 +1022,12 @@ async function runLoop(options) {
         process.exitCode = 1;
         return;
     }
+    // --features is an issue-driven (--prefix) knob. Spec-driven runs always process
+    // the feature tree the planning phase produces, so a user-supplied --features is
+    // a no-op here — warn rather than silently ignore.
+    if (options.features && work && flow) {
+        console.warn('\x1b[33mWARN\x1b[0m --features has no effect with --work/--flow (spec-driven mode always processes the planned feature tree; feature roots that own child tasks are never claimed directly either way)');
+    }
     // Validate that work/flow files exist
     if (work && !fs.existsSync(work)) {
         console.error(`\x1b[31mERR\x1b[0m --work file not found: ${work}`);
@@ -583,10 +1052,10 @@ async function runLoop(options) {
     }
     const dryRun = !options.run;
     const maxIssues = parseInt(options.max || '0', 10);
-    const budget = options.budget || '5.00';
+    const budget = options.budget || exports.DEFAULT_BUDGET_USD;
     const resumeLimit = parseInt(options.resumeLimit || '3', 10);
     const pollInterval = parseInt(options.pollInterval || '60', 10);
-    const model = options.model || 'claude-opus-4-6';
+    const model = resolveModel(options.model);
     const perIssueBranch = options.perIssueBranch || false;
     const noBranch = options.branch === false;
     let includeFeatures = options.features || false;
@@ -596,6 +1065,17 @@ async function runLoop(options) {
     const projectDir = process.cwd();
     const logDir = path.join(projectDir, 'labs', 'claude-runs');
     fs.mkdirSync(logDir, { recursive: true });
+    // Hard requirement (Decision #6): beads must be in Dolt server mode so concurrent
+    // worktrees share one issue DB. Runs always — embedded mode is a footgun for any
+    // bd concurrency and the check is cheap.
+    try {
+        assertDoltServerMode(projectDir);
+    }
+    catch (e) {
+        console.error(`\x1b[31m[bd-loop]\x1b[0m ${e.message}`);
+        process.exitCode = 1;
+        return;
+    }
     // Planning mode dry-run
     if (dryRun && work && resolvedFlow) {
         const workContent = fs.readFileSync(work, 'utf8');
@@ -645,31 +1125,48 @@ async function runLoop(options) {
     if (dryRun) {
         console.log('\x1b[33m[bd-loop]\x1b[0m DRY RUN — add --run to execute');
     }
-    // Set up shared branch
-    let originalBranch;
-    let sharedBranch;
-    if (!noBranch && !perIssueBranch) {
-        sharedBranch = `work/${prefix}`;
-        console.log(`\x1b[32m[bd-loop]\x1b[0m Branch strategy: shared branch \x1b[34m${sharedBranch}\x1b[0m`);
-    }
-    if (sharedBranch && !dryRun) {
-        originalBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf8' }).trim();
-        console.log(`\x1b[32m[bd-loop]\x1b[0m   Checking out branch: ${sharedBranch}`);
+    // Always-worktree (Slice 1): the loop runs inside its own git worktree at
+    // ../boop-<scope> on branch work/<scope> so N loops run concurrently without
+    // colliding; main is never checked out. --no-branch opts out (in-place, today's
+    // single-tenant behavior). Manual merge is the v1 contract — no --merge yet.
+    const worktreeMode = work && resolvedFlow ? 'work-flow' : 'prefix';
+    let worktreeCtx;
+    let loopCwd = projectDir;
+    if (noBranch) {
+        console.log(`\x1b[32m[bd-loop]\x1b[0m Branch strategy: in-place on current branch (--no-branch)`);
+    }
+    else if (!dryRun) {
+        // Worktrees reuse the running shared Dolt server — they never start one.
+        const server = discoverDoltServer(projectDir);
+        if (!server) {
+            console.error(`\x1b[31m[bd-loop]\x1b[0m No shared Dolt server discovered (.beads/dolt-server.port missing). ` +
+                `Start it with \`bd dolt start\` before running the loop; worktrees never start their own server.`);
+            process.exitCode = 1;
+            return;
+        }
+        if (server.alive === false) {
+            console.warn(`\x1b[33m[bd-loop]\x1b[0m Dolt server pid ${server.pid} on port ${server.port} does not appear to be running; ` +
+                `bd calls may fail. Continuing (liveness check is best-effort).`);
+        }
         try {
-            (0, child_process_1.execSync)(`git checkout -b ${sharedBranch} 2>/dev/null`, { encoding: 'utf8' });
+            worktreeCtx = createWorktree(prefix, worktreeMode, projectDir);
         }
-        catch {
-            try {
-                (0, child_process_1.execSync)(`git checkout ${sharedBranch}`, { encoding: 'utf8' });
-                console.log(`\x1b[33m[bd-loop]\x1b[0m   Branch ${sharedBranch} already exists, checked out`);
-            }
-            catch {
-                console.error(`\x1b[31m[bd-loop]\x1b[0m   Failed to checkout shared branch ${sharedBranch}`);
-                console.error('\x1b[31m[bd-loop]\x1b[0m   You may have uncommitted changes — try: git stash');
-                process.exitCode = 1;
-                return;
-            }
+        catch (e) {
+            console.error(`\x1b[31m[bd-loop]\x1b[0m ${e.message}`);
+            process.exitCode = 1;
+            return;
         }
+        loopCwd = worktreeCtx.path;
+        writeWorktreeMetadata(worktreeCtx, {
+            workPath: work,
+            flowPath: resolvedFlow,
+            boopVersion: getBoopVersion(),
+            startTime: new Date().toISOString(),
+            operator: getGitUserName(projectDir),
+            budget,
+            model,
+        });
+        console.log(`\x1b[32m[bd-loop]\x1b[0m Worktree: \x1b[34m${worktreeCtx.path}\x1b[0m on branch \x1b[34m${worktreeCtx.branch}\x1b[0m`);
     }
     let totalProcessed = 0;
     let totalClosed = 0;
@@ -677,6 +1174,13 @@ async function runLoop(options) {
     while (true) {
         const nextId = prefix ? findNextIssue(prefix, includeFeatures) : null;
         if (!nextId) {
+            // Spec-driven safety net: the filter removes the workflow-owned feature
+            // root from claimable work, so when its chain completes nobody may have
+            // closed it. Close it here (no-op if the closeout child already did, or if
+            // children remain open) before deciding to poll or terminate.
+            if (work && resolvedFlow && prefix) {
+                closeCompletedFeatureRoot(prefix);
+            }
             if (poll) {
                 console.log(`\x1b[36m[bd-loop]\x1b[0m No ready issues for prefix '${prefix}'. Polling again in ${pollInterval}s...`);
                 await sleep(pollInterval * 1000);
@@ -704,11 +1208,14 @@ async function runLoop(options) {
                         break;
                     console.log(`  \x1b[34m${info.id}\x1b[0m (P${info.priority} ${info.issue_type}) — ${info.title}`);
                     console.log(`    Would run: claude -p --max-budget-usd ${budget} --session-id <uuid>`);
-                    if (sharedBranch) {
-                        console.log(`    Branch: ${sharedBranch} (shared)`);
+                    if (noBranch) {
+                        console.log(`    Branch: in-place (--no-branch)`);
                     }
-                    else if (!noBranch) {
-                        console.log(`    Branch: fix/${info.id}`);
+                    else {
+                        console.log(`    Worktree: ../boop-${prefix} (branch work/${prefix})`);
+                        if (perIssueBranch) {
+                            console.log(`    Per-issue branch: fix/${info.id} (inside worktree)`);
+                        }
                     }
                     console.log(`    Resume limit: ${resumeLimit} attempts`);
                     console.log('');
@@ -740,6 +1247,7 @@ async function runLoop(options) {
             perIssueBranch,
             noBranch,
             logDir,
+            cwd: loopCwd,
         });
         results.push(result);
         if (result.closed)
@@ -749,15 +1257,9 @@ async function runLoop(options) {
             break;
         }
     }
-    // Return to original branch
-    if (sharedBranch && !dryRun && originalBranch) {
-        try {
-            (0, child_process_1.execSync)(`git checkout ${originalBranch} 2>/dev/null`);
-        }
-        catch {
-            // Best effort
-        }
-    }
+    // 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 —
+    // main's working tree was never touched.
     // Summary
     console.log('');
     console.log('\x1b[32m[bd-loop]\x1b[0m ━━━ Summary ━━━');
@@ -770,7 +1272,17 @@ async function runLoop(options) {
         }
     }
     console.log(`\x1b[32m[bd-loop]\x1b[0m   Logs: ${logDir}/`);
+    if (worktreeCtx) {
+        console.log(`\x1b[32m[bd-loop]\x1b[0m   Worktree: ${worktreeCtx.path} (branch ${worktreeCtx.branch})`);
+        console.log(`\x1b[32m[bd-loop]\x1b[0m   Review and merge by hand, e.g.: git -C ${projectDir} merge ${worktreeCtx.branch}`);
+    }
     if (options.json) {
-        console.log(JSON.stringify({ prefix, totalProcessed, totalClosed, results }, null, 2));
+        console.log(JSON.stringify({
+            prefix,
+            totalProcessed,
+            totalClosed,
+            results,
+            worktree: worktreeCtx ? { path: worktreeCtx.path, branch: worktreeCtx.branch, mode: worktreeCtx.mode } : null,
+        }, null, 2));
     }
 }