sequant 1.15.1 → 1.15.3

package/dist/src/commands/run.js

@@ -6,7 +6,7 @@
  */
 import chalk from "chalk";
 import { spawnSync } from "child_process";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import path from "path";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { getManifest } from "../lib/manifest.js";
@@ -23,6 +23,9 @@ import { determineOutcome, } from "../lib/workflow/metrics-schema.js";
 import { getResumablePhasesForIssue } from "../lib/workflow/phase-detection.js";
 import { ui, colors } from "../lib/cli-ui.js";
 import { PhaseSpinner } from "../lib/phase-spinner.js";
+import { getGitDiffStats, getCommitHash, } from "../lib/workflow/git-diff-utils.js";
+import { getTokenUsageForRun } from "../lib/workflow/token-utils.js";
+import { reconcileStateAtStartup } from "../lib/workflow/state-utils.js";
 /**
  * Slugify a title for branch naming
  */
@@ -94,6 +97,92 @@ function findExistingWorktree(branch) {
     }
     return null;
 }
+/**
+ * Check if a worktree is stale (behind origin/main) and should be recreated
+ *
+ * @param worktreePath - Path to the worktree
+ * @param verbose - Enable verbose output
+ * @returns Freshness check result
+ */
+export function checkWorktreeFreshness(worktreePath, verbose) {
+    const result = {
+        isStale: false,
+        commitsBehind: 0,
+        hasUncommittedChanges: false,
+        hasUnpushedCommits: false,
+    };
+    // Fetch latest main to ensure accurate comparison
+    spawnSync("git", ["-C", worktreePath, "fetch", "origin", "main"], {
+        stdio: "pipe",
+        timeout: 30000,
+    });
+    // Check for uncommitted changes
+    const statusResult = spawnSync("git", ["-C", worktreePath, "status", "--porcelain"], { stdio: "pipe" });
+    if (statusResult.status === 0) {
+        result.hasUncommittedChanges =
+            statusResult.stdout.toString().trim().length > 0;
+    }
+    // Get merge base with origin/main
+    const mergeBaseResult = spawnSync("git", ["-C", worktreePath, "merge-base", "HEAD", "origin/main"], { stdio: "pipe" });
+    if (mergeBaseResult.status !== 0) {
+        // Can't determine merge base - not stale
+        return result;
+    }
+    const mergeBase = mergeBaseResult.stdout.toString().trim();
+    // Get origin/main HEAD
+    const mainHeadResult = spawnSync("git", ["-C", worktreePath, "rev-parse", "origin/main"], { stdio: "pipe" });
+    if (mainHeadResult.status !== 0) {
+        return result;
+    }
+    const mainHead = mainHeadResult.stdout.toString().trim();
+    // Count commits behind main
+    if (mergeBase !== mainHead) {
+        const countResult = spawnSync("git", ["-C", worktreePath, "rev-list", "--count", `${mergeBase}..${mainHead}`], { stdio: "pipe" });
+        if (countResult.status === 0) {
+            result.commitsBehind = parseInt(countResult.stdout.toString().trim(), 10);
+            // Consider stale if more than 5 commits behind (configurable threshold)
+            result.isStale = result.commitsBehind > 5;
+        }
+    }
+    // Check for unpushed commits (work in progress)
+    const unpushedResult = spawnSync("git", ["-C", worktreePath, "log", "--oneline", "@{u}..HEAD"], { stdio: "pipe" });
+    if (unpushedResult.status === 0) {
+        result.hasUnpushedCommits =
+            unpushedResult.stdout.toString().trim().length > 0;
+    }
+    if (verbose && result.isStale) {
+        console.log(chalk.gray(`    📊 Worktree is ${result.commitsBehind} commits behind origin/main`));
+    }
+    return result;
+}
+/**
+ * Remove and recreate a stale worktree
+ *
+ * @param existingPath - Path to existing worktree
+ * @param branch - Branch name
+ * @param verbose - Enable verbose output
+ * @returns true if worktree was removed
+ */
+export function removeStaleWorktree(existingPath, branch, verbose) {
+    if (verbose) {
+        console.log(chalk.gray(`    🗑️  Removing stale worktree...`));
+    }
+    // Remove the worktree
+    const removeResult = spawnSync("git", ["worktree", "remove", "--force", existingPath], { stdio: "pipe" });
+    if (removeResult.status !== 0) {
+        const error = removeResult.stderr.toString();
+        console.log(chalk.yellow(`    ⚠️  Could not remove worktree: ${error}`));
+        return false;
+    }
+    // Delete the branch so it can be recreated fresh
+    const deleteResult = spawnSync("git", ["branch", "-D", branch], {
+        stdio: "pipe",
+    });
+    if (deleteResult.status !== 0 && verbose) {
+        console.log(chalk.gray(`    ℹ️  Branch ${branch} not deleted (may not exist locally)`));
+    }
+    return true;
+}
 /**
  * List all active worktrees with their branches
  */
@@ -160,6 +249,37 @@ export function getWorktreeDiffStats(worktreePath) {
         linesAdded: insertionsMatch ? parseInt(insertionsMatch[1], 10) : 0,
     };
 }
+/**
+ * Read cache metrics from QA phase (AC-7)
+ *
+ * @param worktreePath - Path to the worktree
+ * @returns CacheMetrics or undefined if not available
+ */
+function readCacheMetrics(worktreePath) {
+    const cacheMetricsPath = worktreePath
+        ? path.join(worktreePath, ".sequant/.cache/qa/cache-metrics.json")
+        : ".sequant/.cache/qa/cache-metrics.json";
+    if (!existsSync(cacheMetricsPath)) {
+        return undefined;
+    }
+    try {
+        const content = readFileSync(cacheMetricsPath, "utf-8");
+        const data = JSON.parse(content);
+        if (typeof data.hits === "number" &&
+            typeof data.misses === "number" &&
+            typeof data.skipped === "number") {
+            return {
+                hits: data.hits,
+                misses: data.misses,
+                skipped: data.skipped,
+            };
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    return undefined;
+}
 /**
  * Filter phases based on resume status.
  *
@@ -196,11 +316,76 @@ async function ensureWorktree(issueNumber, title, verbose, packageManager, baseB
     const worktreesDir = path.join(path.dirname(gitRoot), "worktrees");
     const worktreePath = path.join(worktreesDir, branch);
     // Check if worktree already exists
-    const existingPath = findExistingWorktree(branch);
+    let existingPath = findExistingWorktree(branch);
+    if (existingPath) {
+        // AC-3: Check if worktree is stale and needs recreation
+        const freshness = checkWorktreeFreshness(existingPath, verbose);
+        if (freshness.isStale) {
+            // AC-3: Handle stale worktrees - check for work in progress
+            if (freshness.hasUncommittedChanges) {
+                console.log(chalk.yellow(`    ⚠️  Worktree is ${freshness.commitsBehind} commits behind main but has uncommitted changes`));
+                console.log(chalk.yellow(`    ℹ️  Keeping existing worktree. Commit or stash changes, then re-run.`));
+                // Continue with existing worktree
+            }
+            else if (freshness.hasUnpushedCommits) {
+                console.log(chalk.yellow(`    ⚠️  Worktree is ${freshness.commitsBehind} commits behind main but has unpushed commits`));
+                console.log(chalk.yellow(`    ℹ️  Keeping existing worktree with WIP commits.`));
+                // Continue with existing worktree
+            }
+            else {
+                // Safe to recreate - no uncommitted/unpushed work
+                console.log(chalk.yellow(`    ⚠️  Worktree is ${freshness.commitsBehind} commits behind main — recreating fresh`));
+                if (removeStaleWorktree(existingPath, branch, verbose)) {
+                    existingPath = null; // Will fall through to create new worktree
+                }
+            }
+        }
+    }
     if (existingPath) {
         if (verbose) {
             console.log(chalk.gray(`    📂 Reusing existing worktree: ${existingPath}`));
         }
+        // In chain mode, rebase existing worktree onto previous chain link
+        if (chainMode && baseBranch) {
+            if (verbose) {
+                console.log(chalk.gray(`    🔄 Rebasing existing worktree onto chain base (${baseBranch})...`));
+            }
+            const rebaseResult = spawnSync("git", ["-C", existingPath, "rebase", baseBranch], { stdio: "pipe" });
+            if (rebaseResult.status !== 0) {
+                const rebaseError = rebaseResult.stderr.toString();
+                // Check if it's a conflict
+                if (rebaseError.includes("CONFLICT") ||
+                    rebaseError.includes("could not apply")) {
+                    console.log(chalk.yellow(`    ⚠️  Rebase conflict detected. Aborting rebase and keeping original branch state.`));
+                    console.log(chalk.yellow(`    ℹ️  Branch ${branch} is not properly chained. Manual rebase may be required.`));
+                    // Abort the rebase to restore branch state
+                    spawnSync("git", ["-C", existingPath, "rebase", "--abort"], {
+                        stdio: "pipe",
+                    });
+                }
+                else {
+                    console.log(chalk.yellow(`    ⚠️  Rebase failed: ${rebaseError.trim()}`));
+                    console.log(chalk.yellow(`    ℹ️  Continuing with branch in its original state.`));
+                }
+                return {
+                    issue: issueNumber,
+                    path: existingPath,
+                    branch,
+                    existed: true,
+                    rebased: false,
+                };
+            }
+            if (verbose) {
+                console.log(chalk.green(`    ✅ Existing worktree rebased onto ${baseBranch}`));
+            }
+            return {
+                issue: issueNumber,
+                path: existingPath,
+                branch,
+                existed: true,
+                rebased: true,
+            };
+        }
         return {
             issue: issueNumber,
             path: existingPath,
@@ -444,9 +629,7 @@ export function createCheckpointCommit(worktreePath, issueNumber, verbose) {
     const commitMessage = `checkpoint(#${issueNumber}): QA passed
 
 This is an automatic checkpoint commit created after issue #${issueNumber}
-passed QA in chain mode. It serves as a recovery point if later issues fail.
-
-Co-Authored-By: Sequant <noreply@sequant.dev>`;
+passed QA in chain mode. It serves as a recovery point if later issues fail.`;
     const commitResult = spawnSync("git", ["-C", worktreePath, "commit", "-m", commitMessage], { stdio: "pipe" });
     if (commitResult.status !== 0) {
         const error = commitResult.stderr.toString();
@@ -458,6 +641,137 @@ Co-Authored-By: Sequant <noreply@sequant.dev>`;
     console.log(chalk.green(`    📌 Checkpoint commit created for #${issueNumber}`));
     return true;
 }
+/**
+ * Lockfile names for different package managers
+ */
+const LOCKFILES = [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "bun.lock",
+    "yarn.lock",
+];
+/**
+ * Check if any lockfile changed during a rebase and re-run install if needed.
+ * This prevents dependency drift when the lockfile was updated on main.
+ * @param worktreePath Path to the worktree
+ * @param packageManager Package manager to use for install
+ * @param verbose Whether to show verbose output
+ * @param preRebaseRef Git ref pointing to pre-rebase HEAD (defaults to ORIG_HEAD,
+ *        which git sets automatically after rebase). Using ORIG_HEAD captures all
+ *        lockfile changes across multi-commit rebases, unlike HEAD~1 which only
+ *        checks the last commit.
+ * @returns true if reinstall was performed, false otherwise
+ * @internal Exported for testing
+ */
+export function reinstallIfLockfileChanged(worktreePath, packageManager, verbose, preRebaseRef = "ORIG_HEAD") {
+    // Compare pre-rebase state to current HEAD to detect all lockfile changes
+    // introduced by the rebase (including changes from main that were pulled in)
+    let lockfileChanged = false;
+    for (const lockfile of LOCKFILES) {
+        const result = spawnSync("git", [
+            "-C",
+            worktreePath,
+            "diff",
+            "--name-only",
+            `${preRebaseRef}..HEAD`,
+            "--",
+            lockfile,
+        ], { stdio: "pipe" });
+        if (result.status === 0 && result.stdout.toString().trim().length > 0) {
+            lockfileChanged = true;
+            if (verbose) {
+                console.log(chalk.gray(`    📦 Lockfile changed: ${lockfile}`));
+            }
+            break;
+        }
+    }
+    if (!lockfileChanged) {
+        if (verbose) {
+            console.log(chalk.gray(`    📦 No lockfile changes detected`));
+        }
+        return false;
+    }
+    // Re-run install to sync node_modules with updated lockfile
+    console.log(chalk.blue(`    📦 Reinstalling dependencies (lockfile changed)...`));
+    const pm = packageManager || "npm";
+    const pmConfig = PM_CONFIG[pm];
+    const [cmd, ...args] = pmConfig.installSilent.split(" ");
+    const installResult = spawnSync(cmd, args, {
+        cwd: worktreePath,
+        stdio: "pipe",
+    });
+    if (installResult.status !== 0) {
+        const error = installResult.stderr.toString();
+        console.log(chalk.yellow(`    ⚠️  Dependency reinstall failed: ${error.trim()}`));
+        return false;
+    }
+    console.log(chalk.green(`    ✅ Dependencies reinstalled`));
+    return true;
+}
+/**
+ * Rebase the worktree branch onto origin/main before PR creation.
+ * This ensures the branch is up-to-date and prevents lockfile drift.
+ *
+ * @param worktreePath Path to the worktree
+ * @param issueNumber Issue number (for logging)
+ * @param packageManager Package manager to use if reinstall needed
+ * @param verbose Whether to show verbose output
+ * @returns RebaseResult indicating success/failure and whether reinstall was performed
+ * @internal Exported for testing
+ */
+export function rebaseBeforePR(worktreePath, issueNumber, packageManager, verbose) {
+    if (verbose) {
+        console.log(chalk.gray(`    🔄 Rebasing #${issueNumber} onto origin/main before PR...`));
+    }
+    // Fetch latest main to ensure we're rebasing onto fresh state
+    const fetchResult = spawnSync("git", ["-C", worktreePath, "fetch", "origin", "main"], {
+        stdio: "pipe",
+    });
+    if (fetchResult.status !== 0) {
+        const error = fetchResult.stderr.toString();
+        console.log(chalk.yellow(`    ⚠️  Could not fetch origin/main: ${error.trim()}`));
+        // Continue anyway - might work with local state
+    }
+    // Perform the rebase
+    const rebaseResult = spawnSync("git", ["-C", worktreePath, "rebase", "origin/main"], { stdio: "pipe" });
+    if (rebaseResult.status !== 0) {
+        const rebaseError = rebaseResult.stderr.toString();
+        // Check if it's a conflict
+        if (rebaseError.includes("CONFLICT") ||
+            rebaseError.includes("could not apply")) {
+            console.log(chalk.yellow(`    ⚠️  Rebase conflict detected. Aborting rebase and keeping original branch state.`));
+            console.log(chalk.yellow(`    ℹ️  PR will be created without rebase. Manual rebase may be required before merge.`));
+            // Abort the rebase to restore branch state
+            spawnSync("git", ["-C", worktreePath, "rebase", "--abort"], {
+                stdio: "pipe",
+            });
+            return {
+                performed: true,
+                success: false,
+                reinstalled: false,
+                error: "Rebase conflict - manual resolution required",
+            };
+        }
+        else {
+            console.log(chalk.yellow(`    ⚠️  Rebase failed: ${rebaseError.trim()}`));
+            console.log(chalk.yellow(`    ℹ️  Continuing with branch in its original state.`));
+            return {
+                performed: true,
+                success: false,
+                reinstalled: false,
+                error: rebaseError.trim(),
+            };
+        }
+    }
+    console.log(chalk.green(`    ✅ Branch rebased onto origin/main`));
+    // Check if lockfile changed and reinstall if needed
+    const reinstalled = reinstallIfLockfileChanged(worktreePath, packageManager, verbose);
+    return {
+        performed: true,
+        success: true,
+        reinstalled,
+    };
+}
 /**
  * Natural language prompts for each phase
  * These prompts will invoke the corresponding skills via natural language
@@ -671,6 +985,11 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         // Get MCP servers config if enabled
         // Reads from Claude Desktop config and passes to SDK for headless MCP support
         const mcpServers = config.mcp ? getMcpServersConfig() : undefined;
+        // Track whether we're actively streaming verbose output
+        // Pausing spinner once per streaming session prevents truncation from rapid pause/resume cycles
+        // (Issue #283: ora's stop() clears the current line, which can truncate output when
+        // pause/resume is called for every chunk in rapid succession)
+        let verboseStreamingActive = false;
         const queryInstance = query({
             prompt,
             options: {
@@ -693,10 +1012,14 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                 // Capture stderr for debugging (helps diagnose early exit failures)
                 stderr: (data) => {
                     capturedStderr += data;
+                    // Write stderr in verbose mode
                     if (config.verbose) {
-                        spinner?.pause();
+                        // Pause spinner once to avoid truncation (Issue #283)
+                        if (!verboseStreamingActive) {
+                            spinner?.pause();
+                            verboseStreamingActive = true;
+                        }
                         process.stderr.write(chalk.red(data));
-                        spinner?.resume();
                     }
                 },
             },
@@ -719,10 +1042,13 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                     capturedOutput += textContent;
                     // Show streaming output in verbose mode
                     if (config.verbose) {
-                        // Pause spinner during verbose streaming to avoid terminal corruption
-                        spinner?.pause();
+                        // Pause spinner once at start of streaming to avoid truncation
+                        // (Issue #283: repeated pause/resume causes ora to clear lines between chunks)
+                        if (!verboseStreamingActive) {
+                            spinner?.pause();
+                            verboseStreamingActive = true;
+                        }
                         process.stdout.write(chalk.gray(textContent));
-                        spinner?.resume();
                     }
                 }
             }
@@ -731,6 +1057,11 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                 resultMessage = message;
             }
         }
+        // Resume spinner after streaming completes (if we paused it)
+        if (verboseStreamingActive) {
+            spinner?.resume();
+            verboseStreamingActive = false;
+        }
         clearTimeout(timeoutId);
         // Clear abort controller from shutdown manager
         if (shutdownManager) {
@@ -844,14 +1175,30 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
 const COLD_START_THRESHOLD_SECONDS = 60;
 const COLD_START_MAX_RETRIES = 2;
 /**
- * Execute a phase with automatic retry for cold-start failures.
- * If a phase fails within COLD_START_THRESHOLD_SECONDS, it's likely a subprocess
- * initialization issue — retry up to COLD_START_MAX_RETRIES times before giving up.
+ * Execute a phase with automatic retry for cold-start failures and MCP fallback.
+ *
+ * Retry strategy:
+ * 1. If phase fails within COLD_START_THRESHOLD_SECONDS, retry up to COLD_START_MAX_RETRIES times
+ * 2. If still failing and MCP is enabled, retry once with MCP disabled (npx-based MCP servers
+ *    can fail on first run due to cold-cache issues)
+ *
+ * The MCP fallback is safe because MCP servers are optional enhancements, not required
+ * for core functionality.
+ */
+/**
+ * @internal Exported for testing only
  */
-async function executePhaseWithRetry(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner) {
+export async function executePhaseWithRetry(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner, 
+/** @internal Injected for testing — defaults to module-level executePhase */
+executePhaseFn = executePhase) {
+    // Skip retry logic if explicitly disabled
+    if (config.retry === false) {
+        return executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+    }
     let lastResult;
+    // Phase 1: Cold-start retry attempts (with MCP enabled if configured)
     for (let attempt = 0; attempt <= COLD_START_MAX_RETRIES; attempt++) {
-        lastResult = await executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+        lastResult = await executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
         const duration = lastResult.durationSeconds ?? 0;
         // Success or genuine failure (took long enough to be real work)
         if (lastResult.success || duration >= COLD_START_THRESHOLD_SECONDS) {
@@ -864,6 +1211,28 @@ async function executePhaseWithRetry(issueNumber, phase, config, sessionId, work
             }
         }
     }
+    // Capture the original error for better diagnostics
+    const originalError = lastResult.error;
+    // Phase 2: MCP fallback - if MCP is enabled and we're still failing, try without MCP
+    // This handles npx-based MCP servers that fail on first run due to cold-cache issues
+    if (config.mcp && !lastResult.success) {
+        console.log(chalk.yellow(`\n    ⚠️ Phase failed with MCP enabled, retrying without MCP...`));
+        // Create config copy with MCP disabled
+        const configWithoutMcp = {
+            ...config,
+            mcp: false,
+        };
+        const retryResult = await executePhaseFn(issueNumber, phase, configWithoutMcp, sessionId, worktreePath, shutdownManager, spinner);
+        if (retryResult.success) {
+            console.log(chalk.green(`    ✓ Phase succeeded without MCP (MCP cold-start issue detected)`));
+            return retryResult;
+        }
+        // Both attempts failed - return original error for better diagnostics
+        return {
+            ...lastResult,
+            error: originalError,
+        };
+    }
     return lastResult;
 }
 /**
@@ -1160,6 +1529,10 @@ export async function runCommand(issues, options) {
     const mcpEnabled = mergedOptions.noMcp
         ? false
         : (settings.run.mcp ?? DEFAULT_CONFIG.mcp);
+    // Resolve retry setting: CLI flag → settings.run.retry → default (true)
+    const retryEnabled = mergedOptions.noRetry
+        ? false
+        : (settings.run.retry ?? true);
     const config = {
         ...DEFAULT_CONFIG,
         phases: explicitPhases ?? DEFAULT_PHASES,
@@ -1171,6 +1544,7 @@ export async function runCommand(issues, options) {
         maxIterations: mergedOptions.maxIterations ?? DEFAULT_CONFIG.maxIterations,
         noSmartTests: mergedOptions.noSmartTests ?? false,
         mcp: mcpEnabled,
+        retry: retryEnabled,
     };
     // Propagate verbose mode to UI config so spinners use text-only mode.
     // This prevents animated spinner control characters from colliding with
@@ -1190,12 +1564,24 @@ export async function runCommand(issues, options) {
             sequential: config.sequential,
             qualityLoop: config.qualityLoop,
             maxIterations: config.maxIterations,
+            chain: mergedOptions.chain,
+            qaGate: mergedOptions.qaGate,
         };
-        logWriter = new LogWriter({
-            logPath: mergedOptions.logPath ?? settings.run.logPath,
-            verbose: config.verbose,
-        });
-        await logWriter.initialize(runConfig);
+        try {
+            logWriter = new LogWriter({
+                logPath: mergedOptions.logPath ?? settings.run.logPath,
+                verbose: config.verbose,
+                startCommit: getCommitHash(process.cwd()),
+            });
+            await logWriter.initialize(runConfig);
+        }
+        catch (err) {
+            // Log initialization failure is non-fatal - warn and continue without logging
+            // Common causes: permissions issues, disk full, invalid path
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            console.log(chalk.yellow(`  ⚠️ Log initialization failed, continuing without logging: ${errorMessage}`));
+            logWriter = null;
+        }
     }
     // Initialize state manager for persistent workflow state tracking
     // State tracking is always enabled (unless dry run)
@@ -1239,7 +1625,62 @@ export async function runCommand(issues, options) {
     if (stateManager) {
         console.log(chalk.gray(`  State tracking: enabled`));
     }
+    if (mergedOptions.force) {
+        console.log(chalk.yellow(`  Force mode: enabled (bypass state guard)`));
+    }
     console.log(chalk.gray(`  Issues: ${issueNumbers.map((n) => `#${n}`).join(", ")}`));
+    // ============================================================================
+    // Pre-flight State Guard (#305)
+    // ============================================================================
+    // AC-5: Auto-cleanup at run start - reconcile stale ready_for_merge states
+    if (stateManager && !config.dryRun) {
+        try {
+            const reconcileResult = await reconcileStateAtStartup({
+                verbose: config.verbose,
+            });
+            if (reconcileResult.success && reconcileResult.advanced.length > 0) {
+                console.log(chalk.gray(`  State reconciled: ${reconcileResult.advanced.map((n) => `#${n}`).join(", ")} → merged`));
+            }
+        }
+        catch {
+            // AC-8: Graceful degradation - don't block execution on reconciliation failure
+            if (config.verbose) {
+                console.log(chalk.yellow(`  ⚠️  State reconciliation failed, continuing...`));
+            }
+        }
+    }
+    // AC-1 & AC-2: Pre-flight state guard - skip completed issues unless --force
+    if (stateManager && !config.dryRun && !mergedOptions.force) {
+        const skippedIssues = [];
+        const activeIssues = [];
+        for (const issueNumber of issueNumbers) {
+            try {
+                const issueState = await stateManager.getIssueState(issueNumber);
+                if (issueState &&
+                    (issueState.status === "ready_for_merge" ||
+                        issueState.status === "merged")) {
+                    skippedIssues.push(issueNumber);
+                    console.log(chalk.yellow(`  ⚠️  #${issueNumber}: already ${issueState.status} — skipping (use --force to re-run)`));
+                }
+                else {
+                    activeIssues.push(issueNumber);
+                }
+            }
+            catch {
+                // AC-8: Graceful degradation - if state check fails, include the issue
+                activeIssues.push(issueNumber);
+            }
+        }
+        // Update issueNumbers to only include active issues
+        if (skippedIssues.length > 0) {
+            issueNumbers = activeIssues;
+            if (issueNumbers.length === 0) {
+                console.log(chalk.yellow(`\n  All issues already completed. Use --force to re-run.`));
+                return;
+            }
+            console.log(chalk.gray(`  Active issues: ${issueNumbers.map((n) => `#${n}`).join(", ")}`));
+        }
+    }
     // Worktree isolation is enabled by default for multi-issue runs
     const useWorktreeIsolation = mergedOptions.worktreeIsolation !== false && issueNumbers.length > 0;
     if (useWorktreeIsolation) {
@@ -1297,7 +1738,7 @@ export async function runCommand(issues, options) {
             for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) {
                 const batch = batches[batchIdx];
                 console.log(chalk.blue(`\n  Batch ${batchIdx + 1}/${batches.length}: Issues ${batch.map((n) => `#${n}`).join(", ")}`));
-                const batchResults = await executeBatch(batch, config, logWriter, stateManager, mergedOptions, issueInfoMap, worktreeMap, shutdown);
+                const batchResults = await executeBatch(batch, config, logWriter, stateManager, mergedOptions, issueInfoMap, worktreeMap, shutdown, manifest.packageManager);
                 results.push(...batchResults);
                 // Check if batch failed and we should stop
                 const batchFailed = batchResults.some((r) => !r.success);
@@ -1309,7 +1750,8 @@ export async function runCommand(issues, options) {
         }
         else if (config.sequential) {
             // Sequential execution
-            for (const issueNumber of issueNumbers) {
+            for (let i = 0; i < issueNumbers.length; i++) {
+                const issueNumber = issueNumbers[i];
                 const issueInfo = issueInfoMap.get(issueNumber) ?? {
                     title: `Issue #${issueNumber}`,
                     labels: [],
@@ -1319,7 +1761,10 @@ export async function runCommand(issues, options) {
                 if (logWriter) {
                     logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
                 }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, mergedOptions.chain);
+                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, mergedOptions.chain, // Enable checkpoint commits in chain mode
+                manifest.packageManager, 
+                // In chain mode, only the last issue should trigger pre-PR rebase
+                mergedOptions.chain ? i === issueNumbers.length - 1 : undefined);
                 results.push(result);
                 // Complete issue logging
                 if (logWriter) {
@@ -1374,7 +1819,8 @@ export async function runCommand(issues, options) {
                 if (logWriter) {
                     logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
                 }
-                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, false);
+                const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, mergedOptions, worktreeInfo?.path, worktreeInfo?.branch, shutdown, false, // Parallel mode doesn't support chain
+                manifest.packageManager);
                 results.push(result);
                 // Complete issue logging
                 if (logWriter) {
@@ -1385,7 +1831,9 @@ export async function runCommand(issues, options) {
         // Finalize log
         let logPath = null;
         if (logWriter) {
-            logPath = await logWriter.finalize();
+            logPath = await logWriter.finalize({
+                endCommit: getCommitHash(process.cwd()),
+            });
         }
         // Calculate success/failure counts
         const passed = results.filter((r) => r.success).length;
@@ -1443,6 +1891,8 @@ export async function runCommand(issues, options) {
                     cliFlags.push("--quality-loop");
                 if (mergedOptions.testgen)
                     cliFlags.push("--testgen");
+                // Read token usage from SessionEnd hook files (AC-5, AC-6)
+                const tokenUsage = getTokenUsageForRun(undefined, true); // cleanup after reading
                 // Record the run
                 await metricsWriter.recordRun({
                     issues: issueNumbers,
@@ -1452,11 +1902,15 @@ export async function runCommand(issues, options) {
                     model: process.env.ANTHROPIC_MODEL ?? "opus",
                     flags: cliFlags,
                     metrics: {
-                        tokensUsed: 0, // Token tracking not available from SDK
+                        tokensUsed: tokenUsage.tokensUsed,
                         filesChanged: totalFilesChanged,
                         linesAdded: totalLinesAdded,
                         acceptanceCriteria: 0, // Would need to parse from issue
                         qaIterations: totalQaIterations,
+                        // Token breakdown (AC-6)
+                        inputTokens: tokenUsage.inputTokens || undefined,
+                        outputTokens: tokenUsage.outputTokens || undefined,
+                        cacheTokens: tokenUsage.cacheTokens || undefined,
                     },
                 });
                 if (config.verbose) {
@@ -1514,7 +1968,7 @@ export async function runCommand(issues, options) {
 /**
  * Execute a batch of issues
  */
-async function executeBatch(issueNumbers, config, logWriter, stateManager, options, issueInfoMap, worktreeMap, shutdownManager) {
+async function executeBatch(issueNumbers, config, logWriter, stateManager, options, issueInfoMap, worktreeMap, shutdownManager, packageManager) {
     const results = [];
     for (const issueNumber of issueNumbers) {
         // Check if shutdown was triggered
@@ -1530,7 +1984,8 @@ async function executeBatch(issueNumbers, config, logWriter, stateManager, optio
         if (logWriter) {
             logWriter.startIssue(issueNumber, issueInfo.title, issueInfo.labels);
         }
-        const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, options, worktreeInfo?.path, worktreeInfo?.branch, shutdownManager, false);
+        const result = await runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueInfo.title, issueInfo.labels, options, worktreeInfo?.path, worktreeInfo?.branch, shutdownManager, false, // Batch mode doesn't support chain
+        packageManager);
         results.push(result);
         // Complete issue logging
         if (logWriter) {
@@ -1542,7 +1997,7 @@ async function executeBatch(issueNumbers, config, logWriter, stateManager, optio
 /**
  * Execute all phases for a single issue with logging and quality loop
  */
-async function runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueTitle, labels, options, worktreePath, branch, shutdownManager, chainMode) {
+async function runIssueWithLogging(issueNumber, config, logWriter, stateManager, issueTitle, labels, options, worktreePath, branch, shutdownManager, chainMode, packageManager, isLastInChain) {
     const startTime = Date.now();
     const phaseResults = [];
     let loopTriggered = false;
@@ -1630,6 +2085,7 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
             phaseResults.push(specResult);
             specAlreadyRan = true;
             // Log spec phase result
+            // Note: Spec runs in main repo, not worktree, so no git diff stats
             if (logWriter) {
                 const phaseLog = createPhaseLogFromTiming("spec", issueNumber, specStartTime, specEndTime, specResult.success
                     ? "success"
@@ -1771,16 +2227,30 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
                 }
             }
             phaseResults.push(result);
-            // Log phase result
+            // Log phase result with observability data (AC-1, AC-2, AC-3, AC-7)
             if (logWriter) {
+                // Capture git diff stats for worktree phases (AC-1, AC-3)
+                const diffStats = worktreePath
+                    ? getGitDiffStats(worktreePath)
+                    : undefined;
+                // Capture commit hash after phase (AC-2)
+                const commitHash = worktreePath
+                    ? getCommitHash(worktreePath)
+                    : undefined;
+                // Read cache metrics for QA phase (AC-7)
+                const cacheMetrics = phase === "qa" ? readCacheMetrics(worktreePath) : undefined;
                 const phaseLog = createPhaseLogFromTiming(phase, issueNumber, phaseStartTime, phaseEndTime, result.success
                     ? "success"
                     : result.error?.includes("Timeout")
                         ? "timeout"
                         : "failure", {
                     error: result.error,
-                    // Include verdict for QA phase (AC-6)
                     verdict: result.verdict,
+                    // Observability fields (AC-1, AC-2, AC-3, AC-7)
+                    filesModified: diffStats?.filesModified,
+                    fileDiffStats: diffStats?.fileDiffStats,
+                    commitHash,
+                    cacheMetrics,
                 });
                 logWriter.logPhase(phaseLog);
             }
@@ -1861,6 +2331,18 @@ async function runIssueWithLogging(issueNumber, config, logWriter, stateManager,
     if (success && chainMode && worktreePath) {
         createCheckpointCommit(worktreePath, issueNumber, config.verbose);
     }
+    // Rebase onto origin/main before PR creation (unless --no-rebase)
+    // This ensures the branch is up-to-date and prevents lockfile drift
+    // AC-1: Non-chain mode rebases onto origin/main before PR
+    // AC-2: Chain mode rebases only the final branch onto origin/main before PR
+    //        (intermediate branches must stay based on their predecessor)
+    const shouldRebase = success &&
+        worktreePath &&
+        !options.noRebase &&
+        (!chainMode || isLastInChain);
+    if (shouldRebase) {
+        rebaseBeforePR(worktreePath, issueNumber, packageManager, config.verbose);
+    }
     return {
         issueNumber,
         success,