sequant 2.2.0 → 2.4.0

package/dist/src/lib/workflow/phase-executor.js

@@ -8,82 +8,26 @@
  * is agent-agnostic.
  */
 import chalk from "chalk";
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
 import { classifyError } from "./error-classifier.js";
 import { ApiError } from "../errors.js";
+import { phaseRegistry } from "./phase-registry.js";
+import { bracketedConsoleLog } from "./notice.js";
 /**
- * Natural language prompts for each phase.
- * Claude Code invokes the corresponding skills via natural language.
- */
-const PHASE_PROMPTS = {
-    spec: "Review GitHub issue #{issue} and create an implementation plan with verification criteria. Run the /spec {issue} workflow.",
-    "security-review": "Perform a deep security analysis for GitHub issue #{issue} focusing on auth, permissions, and sensitive operations. Run the /security-review {issue} workflow.",
-    testgen: "Generate test stubs for GitHub issue #{issue} based on the specification. Run the /testgen {issue} workflow.",
-    exec: "Implement the feature for GitHub issue #{issue} following the spec. Run the /exec {issue} workflow.",
-    test: "Execute structured browser-based testing for GitHub issue #{issue}. Run the /test {issue} workflow.",
-    verify: "Verify the implementation for GitHub issue #{issue} by running commands and capturing output. Run the /verify {issue} workflow.",
-    qa: "Review the implementation for GitHub issue #{issue} against acceptance criteria. Run the /qa {issue} workflow.",
-    loop: "Parse test/QA findings for GitHub issue #{issue} and iterate until quality gates pass. Run the /loop {issue} workflow.",
-    merger: "Integrate and merge completed worktrees for GitHub issue #{issue}. Run the /merger {issue} workflow.",
-};
-/**
- * Self-contained prompts for non-Claude agents (Aider, Codex, etc.).
- * These agents don't have a skill system, so prompts must include
- * full instructions rather than skill invocations.
- */
-const AIDER_PHASE_PROMPTS = {
-    spec: `Read GitHub issue #{issue} using 'gh issue view #{issue}'.
-Create a spec comment on the issue with:
-1. Implementation plan
-2. Acceptance criteria as a checklist
-3. Risk assessment
-Post the comment using 'gh issue comment #{issue} --body "<comment>"'.`,
-    "security-review": `Perform a security review for GitHub issue #{issue}.
-Read the issue with 'gh issue view #{issue}'.
-Check for auth, permissions, injection, and sensitive data issues.
-Post findings as a comment on the issue.`,
-    testgen: `Generate test stubs for GitHub issue #{issue}.
-Read the spec comments on the issue with 'gh issue view #{issue} --comments'.
-Create test files with describe/it blocks covering the acceptance criteria.
-Use the project's existing test framework.`,
-    exec: `Implement the feature described in GitHub issue #{issue}.
-Read the issue and any spec comments with 'gh issue view #{issue} --comments'.
-Follow the implementation plan from the spec.
-Write tests for new functionality.
-Ensure the build passes with 'npm test' and 'npm run build'.`,
-    test: `Test the implementation for GitHub issue #{issue}.
-Run 'npm test' and verify all tests pass.
-Check for edge cases and error handling.`,
-    verify: `Verify the implementation for GitHub issue #{issue}.
-Run relevant commands and capture their output for review.`,
-    qa: `Review the changes for GitHub issue #{issue}.
-Run 'npm test' and 'npm run build' to verify everything works.
-Check each acceptance criterion from the issue comments.
-Output a verdict: READY_FOR_MERGE, AC_MET_BUT_NOT_A_PLUS, or AC_NOT_MET
-with format "### Verdict: <VERDICT>" followed by an explanation.`,
-    loop: `Review test and QA findings for GitHub issue #{issue}.
-Fix any issues identified in the QA feedback.
-Re-run 'npm test' and 'npm run build' until all quality gates pass.`,
-    merger: `Integrate and merge completed worktrees for GitHub issue #{issue}.
-Ensure all branches are up to date and merge cleanly.`,
-};
-/**
- * Phases that require worktree isolation.
- * Only `spec` runs in the main repo (planning-only, no file changes).
- * All other phases must run in the worktree because:
- * 1. They need to read/modify the worktree code
- * 2. Resuming a session created in a different cwd crashes the SDK
+ * Determine whether a phase's session must run inside the issue worktree.
+ *
+ * Sourced from `phaseRegistry.get(phase).requiresWorktree` — replaces the
+ * previous hardcoded `ISOLATED_PHASES` array. Phases must:
+ * 1. Read/modify worktree code
+ * 2. Resume a session from the same cwd it was created in (SDK constraint)
  */
-const ISOLATED_PHASES = [
-    "exec",
-    "security-review",
-    "testgen",
-    "test",
-    "qa",
-    "loop",
-];
+function phaseRequiresWorktree(phase) {
+    return phaseRegistry.has(phase)
+        ? phaseRegistry.get(phase).requiresWorktree
+        : false;
+}
 /**
  * Cold-start retry threshold in seconds.
  * Failures under this duration are likely Claude Code subprocess initialization
@@ -93,15 +37,67 @@ const ISOLATED_PHASES = [
 const COLD_START_THRESHOLD_SECONDS = 60;
 const COLD_START_MAX_RETRIES = 2;
 /**
- * Spec-specific retry configuration.
+ * Leading + trailing throttle. Fires the wrapped callback immediately on the
+ * first call, drops subsequent calls that arrive inside `intervalMs` but
+ * remembers the latest payload, and fires one final "trailing" call with that
+ * latest payload after the window closes. Used to bridge the agent driver's
+ * fine-grained `onOutput` stream (#543) to the TUI's `nowLine` without
+ * either burning the 10 Hz snapshot budget on every chunk or losing the last
+ * useful chunk before the agent goes idle.
+ *
+ * `cancel()` clears the pending timer + payload — call after the consuming
+ * phase finishes so a residual trailing fire doesn't outlive its phase
+ * context. (The orchestrator's stale-phase guard catches it anyway, but
+ * cleanup avoids holding even a no-op timer.)
+ *
+ * @internal Exported for testing only.
+ */
+export function createThrottledReporter(fn, intervalMs) {
+    let timer = null;
+    let pending = null;
+    const report = (text) => {
+        if (timer) {
+            // Inside the throttle window — stash the latest payload for the
+            // trailing fire and drop this call.
+            pending = text;
+            return;
+        }
+        fn(text);
+        timer = setTimeout(() => {
+            const trailing = pending;
+            pending = null;
+            timer = null;
+            if (trailing !== null)
+                report(trailing);
+        }, intervalMs);
+        timer.unref?.();
+    };
+    const cancel = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        pending = null;
+    };
+    return { report, cancel };
+}
+/**
+ * Spec-specific retry configuration. Sourced from the phase registry's
+ * `retryStrategy` field — `phase-registry.ts` is the source of truth.
+ *
  * Spec failures have a higher failure rate (~8.6%) than other phases due to
  * transient GitHub API issues and rate limits. One extra retry with backoff
  * recovers most of these without user intervention.
+ *
+ * Fallback literals (5000 / 1) match the legacy hardcoded values and only
+ * fire if the spec registration is removed or its `retryStrategy` is unset,
+ * which would be a misconfiguration. Tests pin these at 5000 / 1, so any
+ * drift surfaces immediately.
  */
+const SPEC_RETRY_STRATEGY = phaseRegistry.get("spec").retryStrategy;
 /** @internal Exported for testing only */
-export const SPEC_RETRY_BACKOFF_MS = 5000;
+export const SPEC_RETRY_BACKOFF_MS = SPEC_RETRY_STRATEGY?.backoffMs ?? 5000;
 /** @internal Exported for testing only */
-export const SPEC_EXTRA_RETRIES = 1;
+export const SPEC_EXTRA_RETRIES = SPEC_RETRY_STRATEGY?.extraRetries ?? 1;
 export function parseQaVerdict(output) {
     if (!output)
         return null;
@@ -218,29 +214,83 @@ export function formatDuration(seconds) {
     const secs = seconds % 60;
     return `${mins}m ${secs.toFixed(0)}s`;
 }
+/**
+ * Resolve the base ref the zero-diff guard should compare against for
+ * this worktree.
+ *
+ * Reads `branch.<current>.sequantBase` — written by `scripts/new-feature.sh`
+ * when a worktree is created with `--base <branch>`. Returns `origin/<base>`
+ * (prepending `origin/` only when the recorded value does not already
+ * reference a remote). Falls back to `"origin/main"` on missing config,
+ * missing branch, or any git error — preserves the pre-#537 behavior
+ * for worktrees that predate this change or are managed outside
+ * `new-feature.sh`.
+ *
+ * Uses `execFileSync` (not `execSync`) so argv is passed directly to
+ * `execve` without shell interpretation — the recorded value originates
+ * from the user-supplied `--base` CLI flag, and shell-interpolating it
+ * would open a shell-injection vector. With `execFileSync`, a malicious
+ * value is at worst treated as an invalid revspec by git (triggering
+ * the fail-open path), never executed as shell.
+ *
+ * @internal Exported for testing only.
+ */
+export function resolveBaseRef(cwd) {
+    const fallback = "origin/main";
+    let branch;
+    try {
+        branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd,
+            stdio: "pipe",
+        })
+            .toString()
+            .trim();
+    }
+    catch {
+        return fallback;
+    }
+    // Guard against multi-line output (paranoid — should never happen) and
+    // the detached-HEAD case where we have no recorded base to look up.
+    if (!branch || branch === "HEAD" || branch.includes("\n"))
+        return fallback;
+    let recorded;
+    try {
+        recorded = execFileSync("git", ["config", "--get", `branch.${branch}.sequantBase`], { cwd, stdio: "pipe" })
+            .toString()
+            .trim();
+    }
+    catch {
+        return fallback;
+    }
+    if (!recorded || recorded.includes("\n"))
+        return fallback;
+    return recorded.startsWith("origin/") ? recorded : `origin/${recorded}`;
+}
 /**
  * Check whether the exec phase produced any changes in the worktree.
- * Returns true if HEAD has commits unique to it relative to origin/main
- * OR uncommitted work is present.
+ * Returns true if HEAD has commits unique to it relative to the resolved
+ * base ref (see {@link resolveBaseRef}) OR uncommitted work is present.
  *
- * Uses `git rev-list --count origin/main..HEAD` (commits reachable from HEAD
- * but not origin/main) instead of `git diff origin/main..HEAD`, because the
- * two-dot diff also fires in reverse when origin/main has advanced past HEAD
+ * Uses `git rev-list --count <base>..HEAD` (commits reachable from HEAD
+ * but not the base) instead of `git diff <base>..HEAD`, because the
+ * two-dot diff also fires in reverse when the base has advanced past HEAD
  * — on stale branches that would falsely report "has commits" even when the
  * exec phase produced nothing, reintroducing the bug #534 is fixing.
  *
+ * The base ref defaults to `origin/main` but is overridden to the worktree's
+ * recorded base (see #537) so zero-diff execs are still detected on
+ * custom-base worktrees (e.g. those created with `--base feature/epic`).
+ *
  * Fails open (returns true) on git errors — a missing origin ref is better
  * diagnosed as a real zero-diff run than as a false phase failure.
  *
  * @internal Exported for testing only.
  */
 export function hasExecChanges(cwd) {
+    const baseRef = resolveBaseRef(cwd);
     let commitsAhead;
     try {
-        const count = execSync("git rev-list --count origin/main..HEAD", {
-            cwd,
-            stdio: "pipe",
-        })
+        const count = execFileSync("git", ["rev-list", "--count", `${baseRef}..HEAD`], { cwd, stdio: "pipe" })
             .toString()
             .trim();
         commitsAhead = Number.parseInt(count, 10) > 0;
@@ -251,7 +301,10 @@ export function hasExecChanges(cwd) {
     if (commitsAhead)
         return true;
     try {
-        const porcelain = execSync("git status --porcelain", { cwd, stdio: "pipe" })
+        const porcelain = execFileSync("git", ["status", "--porcelain"], {
+            cwd,
+            stdio: "pipe",
+        })
             .toString()
             .trim();
         return porcelain.length > 0;
@@ -276,6 +329,10 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
         stdoutTail: agentResult.stdoutTail,
         exitCode: agentResult.exitCode,
     };
+    const resume = {
+        sessionId: agentResult.sessionId,
+        resumeHandle: agentResult.resumeHandle,
+    };
     if (phase === "qa") {
         const verdict = agentResult.output
             ? parseQaVerdict(agentResult.output)
@@ -291,7 +348,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
                 success: false,
                 durationSeconds,
                 error: `QA verdict: ${verdict}`,
-                sessionId: agentResult.sessionId,
+                ...resume,
                 output: agentResult.output,
                 verdict,
                 summary,
@@ -305,7 +362,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
                 success: false,
                 durationSeconds,
                 error: "QA completed without a parseable verdict",
-                sessionId: agentResult.sessionId,
+                ...resume,
                 output: agentResult.output,
                 summary,
                 ...tails,
@@ -315,7 +372,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
             phase,
             success: true,
             durationSeconds,
-            sessionId: agentResult.sessionId,
+            ...resume,
             output: agentResult.output,
             verdict,
             summary,
@@ -329,7 +386,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
             success: false,
             durationSeconds,
             error: "exec produced no changes (no commits, no uncommitted work)",
-            sessionId: agentResult.sessionId,
+            ...resume,
             output: agentResult.output,
             ...tails,
         };
@@ -338,7 +395,7 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
         phase,
         success: true,
         durationSeconds,
-        sessionId: agentResult.sessionId,
+        ...resume,
         output: agentResult.output,
         ...tails,
     };
@@ -352,8 +409,14 @@ export function mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds
  * @internal Exported for testing only
  */
 export async function getPhasePrompt(phase, issueNumber, agent, promptContext) {
-    const prompts = agent && agent !== "claude-code" ? AIDER_PHASE_PROMPTS : PHASE_PROMPTS;
-    let basePrompt = prompts[phase].replace(/\{issue\}/g, String(issueNumber));
+    const definition = phaseRegistry.get(phase);
+    // Non-claude drivers consult driverOverrides[<driver>] first; fall back to
+    // the default promptTemplate when no override is registered for the driver.
+    const driverPrompt = agent && agent !== "claude-code"
+        ? definition.driverOverrides?.[agent]?.promptTemplate
+        : undefined;
+    const template = driverPrompt ?? definition.promptTemplate;
+    let basePrompt = template.replace(/\{issue\}/g, String(issueNumber));
     // Append phase-specific context (e.g., QA findings for loop phase)
     if (promptContext) {
         basePrompt += `\n\n---\n\n${promptContext}`;
@@ -370,14 +433,14 @@ export async function getPhasePrompt(phase, issueNumber, agent, promptContext) {
 /**
  * Execute a single phase for an issue using the configured AgentDriver.
  */
-async function executePhase(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner) {
+async function executePhase(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner) {
     const startTime = Date.now();
     const prompt = await getPhasePrompt(phase, issueNumber, config.agent, config.promptContext);
     if (config.dryRun) {
         // Dry run - show the prompt that would be sent, then return
         if (config.verbose) {
-            console.log(chalk.gray(`    Would execute: /${phase} ${issueNumber}`));
-            console.log(chalk.gray(`    Prompt: ${prompt}`));
+            bracketedConsoleLog(spinner, chalk.gray(`    Would execute: /${phase} ${issueNumber}`));
+            bracketedConsoleLog(spinner, chalk.gray(`    Prompt: ${prompt}`));
         }
         return {
             phase,
@@ -387,13 +450,13 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         };
     }
     if (config.verbose) {
-        console.log(chalk.gray(`    Prompt: ${prompt}`));
-        if (worktreePath && ISOLATED_PHASES.includes(phase)) {
-            console.log(chalk.gray(`    Worktree: ${worktreePath}`));
+        bracketedConsoleLog(spinner, chalk.gray(`    Prompt: ${prompt}`));
+        if (worktreePath && phaseRequiresWorktree(phase)) {
+            bracketedConsoleLog(spinner, chalk.gray(`    Worktree: ${worktreePath}`));
         }
     }
     // Determine working directory and environment
-    const shouldUseWorktree = worktreePath && ISOLATED_PHASES.includes(phase);
+    const shouldUseWorktree = worktreePath && phaseRequiresWorktree(phase);
     const cwd = shouldUseWorktree ? worktreePath : process.cwd();
     // Resolve file context for file-oriented drivers (e.g., Aider --file)
     let files;
@@ -460,17 +523,57 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
     if (config.isolateParallel) {
         env.SEQUANT_ISOLATE_PARALLEL = "true";
     }
+    // Activate interactive relay (#383) unless explicitly disabled.
+    // `relay-check.sh` (sourced from post-tool.sh) reads this env var on every
+    // tool call. Disabled by default in non-interactive scenarios — controlled
+    // via `settings.run.relay` (true by default).
+    if (config.relayEnabled) {
+        env.SEQUANT_RELAY = "true";
+        try {
+            const { resolveBundledFramePath } = await import("../relay/activation.js");
+            const framePath = resolveBundledFramePath();
+            if (framePath)
+                env.SEQUANT_RELAY_FRAME = framePath;
+        }
+        catch {
+            /* relay module unavailable — fall back to bash's search heuristic. */
+        }
+    }
     // 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;
-    // Safety: never resume a session when worktree isolation is active.
-    // Even if THIS phase doesn't use the worktree, a previous phase may have
-    // created the session there. Resuming from a different cwd crashes the SDK
-    // (exit code 1). ISOLATED_PHASES prevents this by design, but this guard
-    // catches edge cases (e.g. a new phase added without updating ISOLATED_PHASES).
-    const canResume = sessionId && !worktreePath;
+    // Activity ping throttle (#543): the agent driver streams text in many small
+    // chunks; the TUI only polls at 10 Hz. Coalesce to ≤2 calls per ~100ms
+    // window (leading + trailing) so we don't burn the poll budget on snapshot
+    // churn but still surface the latest chunk before the agent goes idle.
+    const ACTIVITY_THROTTLE_MS = 100;
+    const onActivity = config.onActivity;
+    const throttle = onActivity
+        ? createThrottledReporter((text) => {
+            try {
+                onActivity(text);
+            }
+            catch {
+                // Activity reporting must never disrupt the run.
+            }
+        }, ACTIVITY_THROTTLE_MS)
+        : undefined;
+    const reportActivity = throttle ? throttle.report : undefined;
+    // Resolve driver before the resume check — eligibility is now driver-owned
+    // (#674). Each driver's `canResume(handle, cwd)` enforces its own contract:
+    // Claude Code requires byte-equal cwd match (session storage is
+    // cwd-namespaced); Aider declines all resume (no session concept); Codex
+    // (when added in #497) folds in AGENTS.md parity. Replacing the prior
+    // `sessionId && !worktreePath` heuristic also unblocks same-worktree resume
+    // across phases.
+    const driver = getDriver(config.agent, {
+        aiderSettings: config.aiderSettings,
+    });
+    const eligibleHandle = resumeHandle && driver.canResume(resumeHandle, cwd)
+        ? resumeHandle
+        : undefined;
     // Build AgentExecutionConfig for the driver
     const agentConfig = {
         cwd,
@@ -479,15 +582,20 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         phaseTimeout: config.phaseTimeout,
         verbose: config.verbose,
         mcp: config.mcp,
-        sessionId: canResume ? sessionId : undefined,
+        resumeHandle: eligibleHandle,
+        sessionId: eligibleHandle?.token,
         files,
-        onOutput: config.verbose
+        onOutput: config.verbose || reportActivity
             ? (text) => {
-                if (!verboseStreamingActive) {
-                    spinner?.pause();
-                    verboseStreamingActive = true;
+                if (config.verbose) {
+                    if (!verboseStreamingActive) {
+                        spinner?.pause();
+                        verboseStreamingActive = true;
+                    }
+                    // eslint-disable-next-line no-restricted-syntax -- spinner is paused above; verbose subprocess streaming bypasses log-update intentionally.
+                    process.stdout.write(chalk.gray(text));
                 }
-                process.stdout.write(chalk.gray(text));
+                reportActivity?.(text);
             }
             : undefined,
         onStderr: config.verbose
@@ -496,15 +604,16 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
                     spinner?.pause();
                     verboseStreamingActive = true;
                 }
+                // eslint-disable-next-line no-restricted-syntax -- spinner is paused above; verbose subprocess streaming bypasses log-update intentionally.
                 process.stderr.write(chalk.red(data));
             }
             : undefined,
     };
-    // Resolve driver from config or default
-    const driver = getDriver(config.agent, {
-        aiderSettings: config.aiderSettings,
-    });
     const agentResult = await driver.executePhase(prompt, agentConfig);
+    // Cancel any pending trailing activity fire — phase is done; the
+    // orchestrator's stale-phase guard would no-op a late call anyway, but
+    // clearing the timer is cheaper than letting it elapse.
+    throttle?.cancel();
     // Resume spinner after execution completes (if we paused it)
     if (verboseStreamingActive) {
         spinner?.resume();
@@ -524,6 +633,7 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         durationSeconds,
         error: agentResult.error,
         sessionId: agentResult.sessionId,
+        resumeHandle: agentResult.resumeHandle,
         stderrTail: agentResult.stderrTail,
         stdoutTail: agentResult.stdoutTail,
         exitCode: agentResult.exitCode,
@@ -543,24 +653,28 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
 /**
  * @internal Exported for testing only
  */
-export async function executePhaseWithRetry(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner, 
+export async function executePhaseWithRetry(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner, 
 /** @internal Injected for testing — defaults to module-level executePhase */
 executePhaseFn = executePhase, 
 /** @internal Injected for testing — defaults to setTimeout-based delay */
 delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // Skip retry logic if explicitly disabled
     if (config.retry === false) {
-        return executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+        return executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
     }
-    // Skip cold-start retries for `loop` phase (#488).
-    // Loop is always a re-run after a failed QA — never a first boot.
-    // Failures at 47-51s are genuine skill failures, not cold-start issues.
-    // Without this guard, 2 cold-start retries + 1 MCP fallback = 3 wasted spawns per loop.
-    const skipColdStartRetry = phase === "loop";
+    // Skip cold-start retries for phases registered with `retryStrategy.maxRetries: 0`.
+    // `loop` is the canonical user (#488) — it's always a re-run after a failed QA,
+    // never a first boot. Failures at 47-51s are genuine skill failures, not cold-start
+    // issues. Without this guard, 2 cold-start retries + 1 MCP fallback = 3 wasted
+    // spawns per loop. Sourcing the decision from the registry makes the rule
+    // data-driven — any future phase registered with `maxRetries: 0` inherits the
+    // same behavior without a code change here.
+    const skipColdStartRetry = phaseRegistry.has(phase) &&
+        phaseRegistry.get(phase).retryStrategy?.maxRetries === 0;
     let lastResult;
     if (skipColdStartRetry) {
         // Single attempt — no cold-start retry loop
-        lastResult = await executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+        lastResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
         if (lastResult.success) {
             return lastResult;
         }
@@ -568,7 +682,7 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     else {
         // Phase 1: Cold-start retry attempts (with MCP enabled if configured)
         for (let attempt = 0; attempt <= COLD_START_MAX_RETRIES; attempt++) {
-            lastResult = await executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+            lastResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
             const duration = lastResult.durationSeconds ?? 0;
             // Success → return immediately
             if (lastResult.success) {
@@ -584,7 +698,7 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
                         const label = typedError instanceof ApiError
                             ? `API error (status ${typedError.metadata.statusCode ?? "unknown"})`
                             : typedError.name;
-                        console.log(chalk.yellow(`\n    ⟳ Retryable error: ${label}, retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
+                        bracketedConsoleLog(spinner, chalk.yellow(`\n    ⟳ Retryable error: ${label}, retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
                     }
                     continue;
                 }
@@ -596,7 +710,7 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
             // Cold-start failure detected — retry
             if (attempt < COLD_START_MAX_RETRIES) {
                 if (config.verbose) {
-                    console.log(chalk.yellow(`\n    ⟳ Cold-start failure detected (${duration.toFixed(1)}s), retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
+                    bracketedConsoleLog(spinner, chalk.yellow(`\n    ⟳ Cold-start failure detected (${duration.toFixed(1)}s), retrying... (attempt ${attempt + 2}/${COLD_START_MAX_RETRIES + 1})`));
                 }
             }
         }
@@ -607,15 +721,15 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // This handles npx-based MCP servers that fail on first run due to cold-cache issues.
     // Skip for `loop` phase — MCP is never the cause of loop failures (#488).
     if (config.mcp && !lastResult.success && !skipColdStartRetry) {
-        console.log(chalk.yellow(`\n    ! Phase failed with MCP enabled, retrying without MCP...`));
+        bracketedConsoleLog(spinner, 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);
+        const retryResult = await executePhaseFn(issueNumber, phase, configWithoutMcp, resumeHandle, worktreePath, shutdownManager, spinner);
         if (retryResult.success) {
-            console.log(chalk.green(`    ✓ Phase succeeded without MCP (MCP cold-start issue detected)`));
+            bracketedConsoleLog(spinner, chalk.green(`    ✓ Phase succeeded without MCP (MCP cold-start issue detected)`));
             return retryResult;
         }
         // Update lastResult for Phase 3 (spec retry)
@@ -632,11 +746,11 @@ delayFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
     // than other phases (~8.6%), so one extra retry with backoff recovers most cases.
     if (phase === "spec" && !lastResult.success) {
         for (let i = 0; i < SPEC_EXTRA_RETRIES; i++) {
-            console.log(chalk.yellow(`\n    ⟳ Spec phase failed, retrying with ${SPEC_RETRY_BACKOFF_MS}ms backoff... (spec retry ${i + 1}/${SPEC_EXTRA_RETRIES})`));
+            bracketedConsoleLog(spinner, chalk.yellow(`\n    ⟳ Spec phase failed, retrying with ${SPEC_RETRY_BACKOFF_MS}ms backoff... (spec retry ${i + 1}/${SPEC_EXTRA_RETRIES})`));
             await delayFn(SPEC_RETRY_BACKOFF_MS);
-            const specRetryResult = await executePhaseFn(issueNumber, phase, config, sessionId, worktreePath, shutdownManager, spinner);
+            const specRetryResult = await executePhaseFn(issueNumber, phase, config, resumeHandle, worktreePath, shutdownManager, spinner);
             if (specRetryResult.success) {
-                console.log(chalk.green(`    ✓ Spec phase succeeded on retry`));
+                bracketedConsoleLog(spinner, chalk.green(`    ✓ Spec phase succeeded on retry`));
                 return specRetryResult;
             }
             lastResult = specRetryResult;

package/dist/src/lib/workflow/phase-mapper.d.ts

@@ -14,29 +14,38 @@ import type { Phase } from "./types.js";
  */
 interface PhaseMapperOptions {
     testgen?: boolean;
+    securityReview?: boolean;
 }
 /**
- * UI-related labels that trigger automatic test phase
- */
-export declare const UI_LABELS: string[];
-/**
- * Bug-related labels that skip spec phase
+ * Bug-related labels (used by downstream metadata consumers).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. The registry-driven
+ * `detectPhasesFromLabels` below does not consult this list. It stays
+ * here because `batch-executor.ts` and other modules read it for
+ * `issueType` propagation and similar non-phase concerns.
  */
 export declare const BUG_LABELS: string[];
 /**
- * Documentation labels that skip spec phase
+ * Documentation labels (used for issueType propagation and downstream metadata).
+ *
+ * Issue-type metadata — NOT phase-trigger rules. See BUG_LABELS comment.
  */
 export declare const DOCS_LABELS: string[];
 /**
- * Complex labels that enable quality loop
+ * Complex labels that enable quality loop.
+ *
+ * Quality-loop trigger — NOT a phase-trigger rule (does not add the loop
+ * *phase*; only flips the `qualityLoop` flag on the run config). Kept
+ * out of the phase registry by design.
  */
 export declare const COMPLEX_LABELS: string[];
 /**
- * Security-related labels that trigger security-review phase
- */
-export declare const SECURITY_LABELS: string[];
-/**
- * Detect phases based on issue labels (like /assess logic)
+ * Detect phases based on issue labels (like /assess logic).
+ *
+ * Label → phase mapping now lives in `PhaseDefinition.detect.labels`. Only
+ * the *insertion position* of detected phases remains baked in here, because
+ * pipeline ordering depends on the phase's role (security-review goes after
+ * spec; test goes before qa).
  */
 export declare function detectPhasesFromLabels(labels: string[]): {
     phases: Phase[];
@@ -55,7 +64,12 @@ export declare function parseRecommendedWorkflow(output: string): {
     qualityLoop: boolean;
 } | null;
 /**
- * Check if an issue has UI-related labels
+ * Check if an issue has UI-related labels.
+ *
+ * Sources the label list from the `test` phase's `detect.labels` entry in
+ * the registry — same data as `detectPhasesFromLabels` consults, just
+ * exposed as a boolean for callers that only need the yes/no answer
+ * (e.g. test phase insertion in `determinePhasesForIssue`).
  */
 export declare function hasUILabels(labels: string[]): boolean;
 /**