sequant 2.1.2 → 2.3.0

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

@@ -11,11 +11,11 @@ import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { createPhaseLogFromTiming } from "./log-writer.js";
 import { classifyError, errorTypeToCategory } from "./error-classifier.js";
-import { PhaseSpinner } from "../phase-spinner.js";
 import { getGitDiffStats, getCommitHash } from "./git-diff-utils.js";
 import { createCheckpointCommit, rebaseBeforePR, createPR, readCacheMetrics, filterResumedPhases, } from "./worktree-manager.js";
 import { executePhaseWithRetry } from "./phase-executor.js";
-import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, BUG_LABELS, DOCS_LABELS, } from "./phase-mapper.js";
+import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, DOCS_LABELS, } from "./phase-mapper.js";
+import { activateRelay, deactivateRelay, } from "../relay/activation.js";
 /**
  * Emit a structured progress line to stderr for MCP progress notifications.
  * Only emits when running under an orchestrator (e.g., MCP server).
@@ -26,6 +26,30 @@ import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIss
  * @param event - Phase lifecycle event: "start", "complete", or "failed"
  * @param extra - Optional fields: durationSeconds (on complete), error (on failed)
  */
+/**
+ * Wrap an `ExecutionConfig` with an `onActivity` hook that re-emits each
+ * agent-output ping as a `"activity"` progress event for the dashboard (#543).
+ *
+ * Returns the input config unchanged when no `onProgress` callback is set,
+ * so non-TUI runs pay no overhead.
+ *
+ * @internal Exported for testing only
+ */
+export function withActivityHook(base, issueNumber, phase, onProgress) {
+    if (!onProgress)
+        return base;
+    return {
+        ...base,
+        onActivity: (text) => {
+            try {
+                onProgress(issueNumber, phase, "activity", { text });
+            }
+            catch {
+                // Activity events must never disrupt the run.
+            }
+        },
+    };
+}
 /**
  * Build enriched prompt context for the /loop phase from a failed phase result (#488).
  * Passes QA verdict, failed ACs, and error directly so the /loop skill doesn't need
@@ -64,9 +88,26 @@ export function emitProgressLine(issue, phase, event = "start", extra) {
     if (extra?.error !== undefined) {
         payload.error = extra.error;
     }
+    // #624 Item 3: surface the outer-loop iteration so MCP consumers (and the
+    // renderer) can label retried events as `(attempt N/M)` / `loop N/M`.
+    if (extra?.iteration !== undefined) {
+        payload.iteration = extra.iteration;
+    }
     const line = `SEQUANT_PROGRESS:${JSON.stringify(payload)}\n`;
     process.stderr.write(line);
 }
+/**
+ * Emit the current run's UUID on stderr so MCP callers can look up the exact
+ * log file produced by this subprocess instead of relying on a fuzzy time
+ * filter (#631). Gated on `SEQUANT_ORCHESTRATOR` so CLI users see nothing.
+ *
+ * Must be called before `emitProgressLine` to satisfy AC-1.
+ */
+export function emitRunIdLine(runId) {
+    if (!process.env.SEQUANT_ORCHESTRATOR)
+        return;
+    process.stderr.write(`SEQUANT_RUN_ID:${runId}\n`);
+}
 export async function getIssueInfo(issueNumber) {
     try {
         const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "title,labels"], { stdio: "pipe" });
@@ -213,6 +254,9 @@ export function getEnvConfig() {
     if (process.env.SEQUANT_TESTGEN === "true") {
         config.testgen = true;
     }
+    if (process.env.SEQUANT_SECURITY_REVIEW === "true") {
+        config.securityReview = true;
+    }
     return config;
 }
 export async function executeBatch(issueNumbers, batchCtx) {
@@ -303,162 +347,174 @@ export async function runIssueWithLogging(ctx) {
             }
         }
     }
+    // Activate relay (#383) if enabled. Tolerates errors — relay must never
+    // block the underlying run.
+    let relayActivation = null;
+    if (config.relayEnabled && !config.dryRun) {
+        try {
+            relayActivation = await activateRelay(issueNumber, {
+                worktreePath,
+                stateManager: stateManager ?? null,
+            });
+            if (relayActivation.warning && config.verbose) {
+                log(chalk.yellow(`    !  Relay: ${relayActivation.warning}`));
+            }
+            else if (relayActivation.activated && config.verbose) {
+                log(chalk.gray(`    Relay active — use \`sequant prompt ${issueNumber} "<msg>"\` to nudge`));
+            }
+        }
+        catch (err) {
+            if (config.verbose) {
+                log(chalk.yellow(`    !  Relay activation failed: ${err}`));
+            }
+        }
+    }
     // Determine phases for this specific issue
     let phases;
     let detectedQualityLoop = false;
     let specAlreadyRan = false;
     if (options.autoDetectPhases) {
-        // Check if labels indicate a simple bug/fix (skip spec entirely)
-        const lowerLabels = labels.map((l) => l.toLowerCase());
-        const isSimpleBugFix = lowerLabels.some((label) => BUG_LABELS.some((bugLabel) => label === bugLabel));
-        // Check if labels indicate documentation-only work (skip spec)
-        const isDocs = lowerLabels.some((label) => DOCS_LABELS.some((docsLabel) => label === docsLabel));
-        if (isSimpleBugFix) {
-            // Simple bug fix: skip spec, go straight to exec → qa
-            phases = ["exec", "qa"];
-            log(chalk.gray(`    Bug fix detected: ${phases.join(" → ")}`));
-        }
-        else if (isDocs) {
-            // Documentation issue: skip spec, lighter pipeline
-            phases = ["exec", "qa"];
-            log(chalk.gray(`    Docs issue detected: ${phases.join(" → ")}`));
+        // #533: Always run spec to get recommended workflow.
+        // The prior bug/docs shortcut (skip spec → exec → qa) was removed because
+        // bug and docs issues often contain design decisions (scope boundaries,
+        // edge cases, test-strategy shifts) that benefit from a spec pass.
+        log(chalk.gray(`    Running spec to determine workflow...`));
+        // RunRenderer (#618) owns spec progress via emitProgressLine + onProgress.
+        // The legacy PhaseSpinner produced duplicate lines for single-issue runs.
+        emitProgressLine(issueNumber, "spec", "start");
+        try {
+            onProgress?.(issueNumber, "spec", "start");
         }
-        else {
-            // Run spec first to get recommended workflow
-            log(chalk.gray(`    Running spec to determine workflow...`));
-            // Create spinner for spec phase (suppressed in parallel mode to prevent interleaving)
-            const specSpinner = config.parallel
-                ? undefined
-                : new PhaseSpinner({
-                    phase: "spec",
-                    phaseIndex: 1,
-                    totalPhases: 3, // Estimate; will be refined after spec
-                    shutdownManager,
-                });
-            specSpinner?.start();
-            emitProgressLine(issueNumber, "spec", "start");
+        catch {
+            /* progress errors must not halt */
+        }
+        // Track spec phase start in state
+        if (stateManager) {
             try {
-                onProgress?.(issueNumber, "spec", "start");
+                await stateManager.updatePhaseStatus(issueNumber, "spec", "in_progress");
             }
             catch {
-                /* progress errors must not halt */
+                // State tracking errors shouldn't stop execution
             }
-            // Track spec phase start in state
+        }
+        const specStartTime = new Date();
+        // Note: spec runs in main repo (not worktree) for planning
+        const specResult = await executePhaseWithRetry(issueNumber, "spec", withActivityHook(config, issueNumber, "spec", onProgress), sessionId, worktreePath, // Will be ignored for spec (non-isolated phase)
+        shutdownManager);
+        const specEndTime = new Date();
+        if (specResult.sessionId) {
+            sessionId = specResult.sessionId;
+            // Update session ID in state for resume capability
             if (stateManager) {
                 try {
-                    await stateManager.updatePhaseStatus(issueNumber, "spec", "in_progress");
+                    await stateManager.updateSessionId(issueNumber, specResult.sessionId);
                 }
                 catch {
                     // State tracking errors shouldn't stop execution
                 }
             }
-            const specStartTime = new Date();
-            // Note: spec runs in main repo (not worktree) for planning
-            const specResult = await executePhaseWithRetry(issueNumber, "spec", config, sessionId, worktreePath, // Will be ignored for spec (non-isolated phase)
-            shutdownManager, specSpinner);
-            const specEndTime = new Date();
-            if (specResult.sessionId) {
-                sessionId = specResult.sessionId;
-                // Update session ID in state for resume capability
-                if (stateManager) {
-                    try {
-                        await stateManager.updateSessionId(issueNumber, specResult.sessionId);
-                    }
-                    catch {
-                        // State tracking errors shouldn't stop execution
-                    }
-                }
+        }
+        phaseResults.push(specResult);
+        specAlreadyRan = true;
+        // Emit completion/failure progress event (AC-8)
+        const specDurationSec = Math.round((specEndTime.getTime() - specStartTime.getTime()) / 1000);
+        if (specResult.success) {
+            const extra = { durationSeconds: specDurationSec };
+            emitProgressLine(issueNumber, "spec", "complete", extra);
+            try {
+                onProgress?.(issueNumber, "spec", "complete", extra);
             }
-            phaseResults.push(specResult);
-            specAlreadyRan = true;
-            // Emit completion/failure progress event (AC-8)
-            const specDurationSec = Math.round((specEndTime.getTime() - specStartTime.getTime()) / 1000);
-            if (specResult.success) {
-                const extra = { durationSeconds: specDurationSec };
-                emitProgressLine(issueNumber, "spec", "complete", extra);
-                try {
-                    onProgress?.(issueNumber, "spec", "complete", extra);
-                }
-                catch {
-                    /* progress errors must not halt */
-                }
+            catch {
+                /* progress errors must not halt */
             }
-            else {
-                const extra = { error: specResult.error ?? "unknown" };
-                emitProgressLine(issueNumber, "spec", "failed", extra);
-                try {
-                    onProgress?.(issueNumber, "spec", "failed", extra);
-                }
-                catch {
-                    /* progress errors must not halt */
-                }
+        }
+        else {
+            const extra = { error: specResult.error ?? "unknown" };
+            emitProgressLine(issueNumber, "spec", "failed", extra);
+            try {
+                onProgress?.(issueNumber, "spec", "failed", extra);
             }
-            // Log spec phase result
-            // Note: Spec runs in main repo, not worktree, so no git diff stats
-            if (logWriter) {
-                // Build errorContext from captured stderr/stdout tails (#447)
-                let specErrorContext;
-                if (!specResult.success && specResult.stderrTail) {
-                    const specError = classifyError(specResult.stderrTail ?? [], specResult.exitCode);
-                    specErrorContext = {
-                        stderrTail: specResult.stderrTail ?? [],
-                        stdoutTail: specResult.stdoutTail ?? [],
-                        exitCode: specResult.exitCode,
-                        category: errorTypeToCategory(specError),
-                        errorType: specError.name,
-                        errorMetadata: specError.metadata,
-                        isRetryable: specError.isRetryable,
-                    };
-                }
-                const phaseLog = createPhaseLogFromTiming("spec", issueNumber, specStartTime, specEndTime, specResult.success
-                    ? "success"
-                    : specResult.error?.includes("Timeout")
-                        ? "timeout"
-                        : "failure", { error: specResult.error, errorContext: specErrorContext });
-                logWriter.logPhase(phaseLog);
+            catch {
+                /* progress errors must not halt */
             }
-            // Track spec phase completion in state
-            if (stateManager) {
+        }
+        // Log spec phase result
+        // Note: Spec runs in main repo, not worktree, so no git diff stats
+        if (logWriter) {
+            // Build errorContext from captured stderr/stdout tails (#447)
+            let specErrorContext;
+            if (!specResult.success && specResult.stderrTail) {
+                const specError = classifyError(specResult.stderrTail ?? [], specResult.exitCode);
+                specErrorContext = {
+                    stderrTail: specResult.stderrTail ?? [],
+                    stdoutTail: specResult.stdoutTail ?? [],
+                    exitCode: specResult.exitCode,
+                    category: errorTypeToCategory(specError),
+                    errorType: specError.name,
+                    errorMetadata: specError.metadata,
+                    isRetryable: specError.isRetryable,
+                };
+            }
+            const phaseLog = createPhaseLogFromTiming("spec", issueNumber, specStartTime, specEndTime, specResult.success
+                ? "success"
+                : specResult.error?.includes("Timeout")
+                    ? "timeout"
+                    : "failure", { error: specResult.error, errorContext: specErrorContext });
+            logWriter.logPhase(phaseLog);
+        }
+        // Track spec phase completion in state
+        if (stateManager) {
+            try {
+                const phaseStatus = specResult.success ? "completed" : "failed";
+                await stateManager.updatePhaseStatus(issueNumber, "spec", phaseStatus, {
+                    error: specResult.error,
+                });
+            }
+            catch {
+                // State tracking errors shouldn't stop execution
+            }
+        }
+        if (!specResult.success) {
+            const durationSeconds = (Date.now() - startTime) / 1000;
+            // Archive relay state on early exit (spec failure).
+            if (relayActivation) {
                 try {
-                    const phaseStatus = specResult.success ? "completed" : "failed";
-                    await stateManager.updatePhaseStatus(issueNumber, "spec", phaseStatus, {
-                        error: specResult.error,
+                    await deactivateRelay(issueNumber, {
+                        phase: "spec",
+                        startedAt: relayActivation.startedAt,
+                        worktreePath,
+                        stateManager: stateManager ?? null,
                     });
                 }
                 catch {
-                    // State tracking errors shouldn't stop execution
+                    /* swallow */
                 }
             }
-            if (!specResult.success) {
-                specSpinner?.fail(specResult.error);
-                const durationSeconds = (Date.now() - startTime) / 1000;
-                return {
-                    issueNumber,
-                    success: false,
-                    phaseResults,
-                    durationSeconds,
-                    loopTriggered: false,
-                };
-            }
-            specSpinner?.succeed();
-            // Parse recommended workflow from spec output
-            const parsedWorkflow = specResult.output
-                ? parseRecommendedWorkflow(specResult.output)
-                : null;
-            if (parsedWorkflow) {
-                // Remove spec from phases since we already ran it
-                phases = parsedWorkflow.phases.filter((p) => p !== "spec");
-                detectedQualityLoop = parsedWorkflow.qualityLoop;
-                log(chalk.gray(`    Spec recommends: ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
-            }
-            else {
-                // Fall back to label-based detection
-                log(chalk.yellow(`    Could not parse spec recommendation, using label-based detection`));
-                const detected = detectPhasesFromLabels(labels);
-                phases = detected.phases.filter((p) => p !== "spec");
-                detectedQualityLoop = detected.qualityLoop;
-                log(chalk.gray(`    Fallback: ${phases.join(" → ")}`));
-            }
+            return {
+                issueNumber,
+                success: false,
+                phaseResults,
+                durationSeconds,
+                loopTriggered: false,
+            };
+        }
+        // Parse recommended workflow from spec output
+        const parsedWorkflow = specResult.output
+            ? parseRecommendedWorkflow(specResult.output)
+            : null;
+        if (parsedWorkflow) {
+            // Remove spec from phases since we already ran it
+            phases = parsedWorkflow.phases.filter((p) => p !== "spec");
+            detectedQualityLoop = parsedWorkflow.qualityLoop;
+            log(chalk.gray(`    Spec recommends: ${phases.join(" → ")}${detectedQualityLoop ? " (quality loop)" : ""}`));
+        }
+        else {
+            // Fall back to label-based detection
+            log(chalk.yellow(`    Could not parse spec recommendation, using label-based detection`));
+            const detected = detectPhasesFromLabels(labels);
+            phases = detected.phases.filter((p) => p !== "spec");
+            detectedQualityLoop = detected.qualityLoop;
+            log(chalk.gray(`    Fallback: ${phases.join(" → ")}`));
         }
     }
     else {
@@ -497,6 +553,21 @@ export async function runIssueWithLogging(ctx) {
             }
         }
     }
+    // Add security-review phase if requested (and spec was in the phases).
+    // Idempotent vs label-based auto-detection — only inserts if not present.
+    if (options.securityReview &&
+        (phases.includes("spec") || specAlreadyRan) &&
+        !phases.includes("security-review")) {
+        if (specAlreadyRan) {
+            phases.unshift("security-review");
+        }
+        else {
+            const specIndex = phases.indexOf("spec");
+            if (specIndex !== -1) {
+                phases.splice(specIndex + 1, 0, "security-review");
+            }
+        }
+    }
     // Build per-issue config with issue type metadata for skill env propagation
     const lowerLabelsForType = labels.map((l) => l.toLowerCase());
     const issueIsDocs = lowerLabelsForType.some((label) => DOCS_LABELS.some((docsLabel) => label === docsLabel));
@@ -514,27 +585,17 @@ export async function runIssueWithLogging(ctx) {
             loopTriggered = true;
         }
         let phasesFailed = false;
-        // Calculate total phases for progress indicator
-        // If spec already ran in auto-detect mode, it's counted separately
-        const totalPhases = specAlreadyRan ? phases.length + 1 : phases.length;
-        const phaseIndexOffset = specAlreadyRan ? 1 : 0;
         for (let phaseIdx = 0; phaseIdx < phases.length; phaseIdx++) {
             const phase = phases[phaseIdx];
-            const phaseNumber = phaseIdx + 1 + phaseIndexOffset;
-            // Create spinner for this phase (suppressed in parallel mode)
-            const phaseSpinner = config.parallel
-                ? undefined
-                : new PhaseSpinner({
-                    phase,
-                    phaseIndex: phaseNumber,
-                    totalPhases,
-                    shutdownManager,
-                    iteration: useQualityLoop ? iteration : undefined,
-                });
-            phaseSpinner?.start();
-            emitProgressLine(issueNumber, phase, "start");
+            // RunRenderer (#618) owns phase progress via emitProgressLine + onProgress.
+            // #624 Item 3: surface the outer-loop iteration on every retried phase
+            // event so the renderer can label them `(attempt N/M)`. First-attempt
+            // events still get `iteration: 1` so the data flow is uniform; the
+            // renderer's `formatRetrySuffix` suppresses the suffix when iteration ≤ 1.
+            const phaseExtra = { iteration };
+            emitProgressLine(issueNumber, phase, "start", phaseExtra);
             try {
-                onProgress?.(issueNumber, phase, "start");
+                onProgress?.(issueNumber, phase, "start", phaseExtra);
             }
             catch {
                 /* progress errors must not halt */
@@ -549,7 +610,7 @@ export async function runIssueWithLogging(ctx) {
                 }
             }
             const phaseStartTime = new Date();
-            const result = await executePhaseWithRetry(issueNumber, phase, issueConfig, sessionId, worktreePath, shutdownManager, phaseSpinner);
+            const result = await executePhaseWithRetry(issueNumber, phase, withActivityHook(issueConfig, issueNumber, phase, onProgress), sessionId, worktreePath, shutdownManager);
             const phaseEndTime = new Date();
             // Capture session ID for subsequent phases
             if (result.sessionId) {
@@ -568,7 +629,7 @@ export async function runIssueWithLogging(ctx) {
             // Emit completion/failure progress event (AC-8)
             const phaseDurationSec = Math.round((phaseEndTime.getTime() - phaseStartTime.getTime()) / 1000);
             if (result.success) {
-                const extra = { durationSeconds: phaseDurationSec };
+                const extra = { durationSeconds: phaseDurationSec, iteration };
                 emitProgressLine(issueNumber, phase, "complete", extra);
                 try {
                     onProgress?.(issueNumber, phase, "complete", extra);
@@ -578,7 +639,7 @@ export async function runIssueWithLogging(ctx) {
                 }
             }
             else {
-                const extra = { error: result.error ?? "unknown" };
+                const extra = { error: result.error ?? "unknown", iteration };
                 emitProgressLine(issueNumber, phase, "failed", extra);
                 try {
                     onProgress?.(issueNumber, phase, "failed", extra);
@@ -645,27 +706,18 @@ export async function runIssueWithLogging(ctx) {
                 }
             }
             if (result.success) {
-                phaseSpinner?.succeed();
+                // Phase succeeded — RunRenderer (#618) updates state via onProgress.
             }
             else {
-                phaseSpinner?.fail(result.error);
                 phasesFailed = true;
                 // If quality loop enabled, run loop phase to fix issues
                 if (useQualityLoop && iteration < maxIterations) {
-                    // Create spinner for loop phase (suppressed in parallel mode)
-                    const loopSpinner = config.parallel
-                        ? undefined
-                        : new PhaseSpinner({
-                            phase: "loop",
-                            phaseIndex: phaseNumber,
-                            totalPhases,
-                            shutdownManager,
-                            iteration,
-                        });
-                    loopSpinner?.start();
-                    emitProgressLine(issueNumber, "loop", "start");
+                    // #624 Item 3 (AC-3.3): the loop phase carries the current outer
+                    // iteration so the live-zone status cell can show `loop N/M`.
+                    const loopStartExtra = { iteration };
+                    emitProgressLine(issueNumber, "loop", "start", loopStartExtra);
                     try {
-                        onProgress?.(issueNumber, "loop", "start");
+                        onProgress?.(issueNumber, "loop", "start", loopStartExtra);
                     }
                     catch {
                         /* progress errors must not halt */
@@ -680,13 +732,13 @@ export async function runIssueWithLogging(ctx) {
                         promptContext: buildLoopContext(result),
                     };
                     const loopStartTime = new Date();
-                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", loopConfig, sessionId, worktreePath, shutdownManager, loopSpinner);
+                    const loopResult = await executePhaseWithRetry(issueNumber, "loop", withActivityHook(loopConfig, issueNumber, "loop", onProgress), sessionId, worktreePath, shutdownManager);
                     const loopEndTime = new Date();
                     phaseResults.push(loopResult);
                     // Emit loop completion/failure progress event (AC-8)
                     const loopDurationSec = Math.round((loopEndTime.getTime() - loopStartTime.getTime()) / 1000);
                     if (loopResult.success) {
-                        const extra = { durationSeconds: loopDurationSec };
+                        const extra = { durationSeconds: loopDurationSec, iteration };
                         emitProgressLine(issueNumber, "loop", "complete", extra);
                         try {
                             onProgress?.(issueNumber, "loop", "complete", extra);
@@ -696,7 +748,7 @@ export async function runIssueWithLogging(ctx) {
                         }
                     }
                     else {
-                        const extra = { error: loopResult.error ?? "unknown" };
+                        const extra = { error: loopResult.error ?? "unknown", iteration };
                         emitProgressLine(issueNumber, "loop", "failed", extra);
                         try {
                             onProgress?.(issueNumber, "loop", "failed", extra);
@@ -709,13 +761,9 @@ export async function runIssueWithLogging(ctx) {
                         sessionId = loopResult.sessionId;
                     }
                     if (loopResult.success) {
-                        loopSpinner?.succeed();
                         // Continue to next iteration
                         break;
                     }
-                    else {
-                        loopSpinner?.fail(loopResult.error);
-                    }
                 }
                 // Stop on first failure (if not in quality loop or loop failed)
                 break;
@@ -747,7 +795,7 @@ export async function runIssueWithLogging(ctx) {
     }
     // Create checkpoint commit in chain mode after QA passes
     if (success && chainMode && worktreePath) {
-        createCheckpointCommit(worktreePath, issueNumber, config.verbose);
+        createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
     }
     // Rebase onto the base branch before PR creation (unless --no-rebase)
     // This ensures the branch is up-to-date and prevents lockfile drift
@@ -766,7 +814,15 @@ export async function runIssueWithLogging(ctx) {
     let prUrl;
     const shouldCreatePR = success && worktreePath && branch && !options.noPr;
     if (shouldCreatePR) {
-        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels);
+        // #605: under --stacked, target predecessor branch (only for non-first,
+        // non-last issues). Last PR keeps `main` so partial progress can land.
+        const stackOptions = chain?.predecessorBranch || chain?.stackManifest
+            ? {
+                prBase: chain.predecessorBranch,
+                stackManifest: chain.stackManifest,
+            }
+            : undefined;
+        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels, stackOptions);
         if (prResult.success && prResult.prNumber && prResult.prUrl) {
             prNumber = prResult.prNumber;
             prUrl = prResult.prUrl;
@@ -784,6 +840,23 @@ export async function runIssueWithLogging(ctx) {
             }
         }
     }
+    // Deactivate relay (#383) — archive inbox/outbox transcripts to
+    // .sequant/logs/relay/ before worktree teardown (AC-D2). Never throws.
+    if (relayActivation) {
+        try {
+            await deactivateRelay(issueNumber, {
+                phase: phaseResults[phaseResults.length - 1]?.phase ?? "exec",
+                startedAt: relayActivation.startedAt,
+                worktreePath,
+                stateManager: stateManager ?? null,
+            });
+        }
+        catch (err) {
+            if (config.verbose) {
+                log(chalk.yellow(`    !  Relay deactivation failed: ${err}`));
+            }
+        }
+    }
     return {
         issueNumber,
         success,

package/dist/src/lib/workflow/config-resolver.js

@@ -146,6 +146,9 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         : (settings.run.retry ?? true);
     const isSequential = mergedOptions.sequential ?? false;
     const isParallel = !isSequential && issueCount > 1;
+    // `--no-relay` arrives from Commander as `mergedOptions.relay === false`;
+    // explicit `false` overrides settings, otherwise settings/default win.
+    const relayEnabled = mergedOptions.relay === false ? false : (settings.run.relay ?? true);
     return {
         ...DEFAULT_CONFIG,
         phases: explicitPhases ?? DEFAULT_PHASES,
@@ -163,5 +166,6 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         agent: mergedOptions.agent ?? settings.run.agent,
         aiderSettings: settings.run.aider,
         isolateParallel: mergedOptions.isolateParallel,
+        relayEnabled,
     };
 }