sequant 2.2.0 → 2.3.0

package/dist/src/lib/workflow/heartbeat.d.ts

@@ -0,0 +1,71 @@
+import type { ShutdownManager } from "../shutdown.js";
+export interface LivenessHeartbeatOptions {
+    /** Polling cadence for heartbeat ticks. Default: 30_000ms */
+    pollIntervalMs?: number;
+    /** Stall threshold (mtime gap) before warning fires. Default: 5min */
+    stallThresholdMs?: number;
+    /** Liveness file whose mtime is the activity proxy. Default: .sequant/state.json */
+    livenessFile?: string;
+    /** When false, no timer is started (heartbeat fully suppressed). Default: true */
+    enabled?: boolean;
+    /**
+     * Per-phase timeout in seconds, used for the "phase timeout in N" suffix
+     * on stall warnings. When omitted, suffix is dropped.
+     */
+    phaseTimeoutSeconds?: number;
+    /** Optional ShutdownManager for graceful cleanup */
+    shutdownManager?: ShutdownManager;
+    /** Override TTY detection (testing). Default: process.stdout.isTTY */
+    isTTY?: boolean;
+    /** Override clock (testing). Default: Date.now */
+    now?: () => number;
+    /** Override stdout writer (testing). Default: process.stdout.write */
+    stdoutWrite?: (s: string) => void;
+    /** Override stderr writer (testing). Default: process.stderr.write */
+    stderrWrite?: (s: string) => void;
+}
+interface PhaseKey {
+    issueNumber: number;
+    phase: string;
+}
+export declare class LivenessHeartbeat {
+    private readonly pollIntervalMs;
+    private readonly stallThresholdMs;
+    private readonly livenessFile;
+    private readonly enabled;
+    private readonly phaseTimeoutSeconds?;
+    private readonly shutdownManager?;
+    private readonly tty;
+    private readonly now;
+    private readonly stdoutWrite;
+    private readonly stderrWrite;
+    private readonly phases;
+    private timer;
+    private stopped;
+    private cleanupRegistered;
+    constructor(options?: LivenessHeartbeatOptions);
+    /**
+     * Begin tracking a phase. Starts the shared poll timer on first call.
+     * No-op if `enabled === false`.
+     */
+    start(entry: PhaseKey & {
+        startedAt: number;
+    }): void;
+    /**
+     * Stop tracking a specific phase. When the last phase is removed, the timer
+     * is cleared so no orphaned polls remain.
+     */
+    stop(key?: PhaseKey): void;
+    /**
+     * Dispose all tracked phases and clear the timer. Idempotent.
+     */
+    dispose(): void;
+    /** Test hook: drive a poll synchronously without waiting on real timers. */
+    tickNow(): void;
+    private tick;
+    private writeHeartbeat;
+    private writeStallWarning;
+}
+/** Convenience factory mirroring `phaseSpinner()`. */
+export declare function livenessHeartbeat(options?: LivenessHeartbeatOptions): LivenessHeartbeat;
+export {};

package/dist/src/lib/workflow/heartbeat.js

@@ -0,0 +1,194 @@
+/**
+ * LivenessHeartbeat — `-q` mode liveness signal + stall warning.
+ *
+ * Surfaces a per-phase liveness line (TTY only) and a one-shot stall warning
+ * (TTY and non-TTY) so users can distinguish "agent working" from "process hung"
+ * without inspecting `state.json` or `ps`/`lsof`.
+ *
+ * Liveness source: mtime of `.sequant/state.json` — written 3-10x per phase by
+ * `StateManager.saveState()`. Zero new infrastructure.
+ *
+ * @see Issue #574
+ */
+import * as fs from "fs";
+import { formatElapsedTime } from "../cli-ui/format.js";
+const DEFAULT_POLL_INTERVAL_MS = 30_000;
+const DEFAULT_STALL_THRESHOLD_MS = 5 * 60_000;
+const DEFAULT_LIVENESS_FILE = ".sequant/state.json";
+const CLEANUP_NAME = "liveness-heartbeat";
+function keyFor(k) {
+    return `${k.issueNumber}:${k.phase}`;
+}
+/**
+ * Format the stall window's elapsed seconds. Floors to whole seconds.
+ */
+function formatStall(seconds) {
+    return formatElapsedTime(Math.floor(seconds));
+}
+export class LivenessHeartbeat {
+    pollIntervalMs;
+    stallThresholdMs;
+    livenessFile;
+    enabled;
+    phaseTimeoutSeconds;
+    shutdownManager;
+    tty;
+    now;
+    stdoutWrite;
+    stderrWrite;
+    phases = new Map();
+    timer = null;
+    stopped = false;
+    cleanupRegistered = false;
+    constructor(options = {}) {
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.stallThresholdMs =
+            options.stallThresholdMs ?? DEFAULT_STALL_THRESHOLD_MS;
+        this.livenessFile = options.livenessFile ?? DEFAULT_LIVENESS_FILE;
+        this.enabled = options.enabled ?? true;
+        this.phaseTimeoutSeconds = options.phaseTimeoutSeconds;
+        this.shutdownManager = options.shutdownManager;
+        this.tty = options.isTTY ?? Boolean(process.stdout.isTTY);
+        this.now = options.now ?? Date.now;
+        this.stdoutWrite =
+            options.stdoutWrite ?? ((s) => void process.stdout.write(s));
+        this.stderrWrite =
+            options.stderrWrite ?? ((s) => void process.stderr.write(s));
+    }
+    /**
+     * Begin tracking a phase. Starts the shared poll timer on first call.
+     * No-op if `enabled === false`.
+     */
+    start(entry) {
+        if (!this.enabled || this.stopped)
+            return;
+        const key = keyFor(entry);
+        this.phases.set(key, {
+            issueNumber: entry.issueNumber,
+            phase: entry.phase,
+            startedAt: entry.startedAt,
+            warningFired: false,
+        });
+        if (this.timer === null) {
+            this.timer = setInterval(() => this.tick(), this.pollIntervalMs);
+            // Don't keep the event loop alive solely for the heartbeat.
+            if (typeof this.timer.unref === "function")
+                this.timer.unref();
+        }
+        if (this.shutdownManager && !this.cleanupRegistered) {
+            this.shutdownManager.registerCleanup(CLEANUP_NAME, async () => {
+                this.dispose();
+            });
+            this.cleanupRegistered = true;
+        }
+    }
+    /**
+     * Stop tracking a specific phase. When the last phase is removed, the timer
+     * is cleared so no orphaned polls remain.
+     */
+    stop(key) {
+        if (key) {
+            this.phases.delete(keyFor(key));
+        }
+        else {
+            this.phases.clear();
+        }
+        // Clear the timer when no phases remain so we don't poll uselessly between
+        // phases. We do NOT call dispose() here — that would set `stopped = true`
+        // and silently no-op the next start() in a sequential single-issue run
+        // (spec → stop → exec). Terminal teardown is dispose() called from the
+        // run.ts `finally` block.
+        if (this.phases.size === 0 && this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Dispose all tracked phases and clear the timer. Idempotent.
+     */
+    dispose() {
+        this.stopped = true;
+        this.phases.clear();
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        if (this.shutdownManager && this.cleanupRegistered) {
+            this.shutdownManager.unregisterCleanup(CLEANUP_NAME);
+            this.cleanupRegistered = false;
+        }
+    }
+    /** Test hook: drive a poll synchronously without waiting on real timers. */
+    tickNow() {
+        this.tick();
+    }
+    tick() {
+        if (this.stopped || this.phases.size === 0)
+            return;
+        const now = this.now();
+        for (const entry of this.phases.values()) {
+            let mtimeMs;
+            try {
+                const stat = fs.statSync(this.livenessFile);
+                mtimeMs = stat.mtimeMs;
+            }
+            catch {
+                // ENOENT (state.json not yet written) or EACCES — treat as no signal.
+                // Skip both heartbeat and stall logic this tick.
+                mtimeMs = null;
+            }
+            if (mtimeMs === null)
+                continue;
+            const sinceActivityMs = Math.max(0, now - mtimeMs);
+            const elapsedSinceStartMs = Math.max(0, now - entry.startedAt);
+            // AC-1: TTY heartbeat line — rewrite via \r.
+            if (this.tty) {
+                this.writeHeartbeat(entry, elapsedSinceStartMs, sinceActivityMs);
+            }
+            // AC-2: One-shot stall warning (TTY and non-TTY).
+            if (sinceActivityMs >= this.stallThresholdMs) {
+                if (!entry.warningFired) {
+                    this.writeStallWarning(entry, sinceActivityMs, elapsedSinceStartMs);
+                    entry.warningFired = true;
+                }
+            }
+            else if (entry.warningFired) {
+                // Activity resumed — reset for the next stall window.
+                entry.warningFired = false;
+            }
+        }
+    }
+    writeHeartbeat(entry, elapsedSinceStartMs, sinceActivityMs) {
+        if (this.stopped)
+            return;
+        const elapsed = formatElapsedTime(Math.floor(elapsedSinceStartMs / 1000));
+        const sinceActivity = formatElapsedTime(Math.floor(sinceActivityMs / 1000));
+        // \r rewrites current line; \x1b[K clears the rest in case the new line is
+        // shorter than the old one.
+        const line = `\r  ▸ #${entry.issueNumber}  ${entry.phase}  (${elapsed} elapsed, last log update ${sinceActivity} ago)`;
+        this.stdoutWrite(line);
+    }
+    writeStallWarning(entry, sinceActivityMs, elapsedSinceStartMs) {
+        if (this.stopped)
+            return;
+        const stallStr = formatStall(sinceActivityMs / 1000);
+        let suffix = "";
+        if (this.phaseTimeoutSeconds !== undefined) {
+            const remaining = this.phaseTimeoutSeconds - elapsedSinceStartMs / 1000;
+            if (remaining > 0) {
+                suffix = ` (phase timeout in ${formatElapsedTime(Math.floor(remaining))})`;
+            }
+        }
+        // Prefix \r\x1b[K to clear any in-flight TTY heartbeat on this line, then
+        // emit the warning on its own line. Non-TTY mode prints leading control
+        // chars too — they are inert when not interpreted, and matter for TTY co-
+        // existence with the heartbeat rewrite.
+        const prefix = this.tty ? "\r" : "";
+        const line = `${prefix}  ⚠ #${entry.issueNumber}  ${entry.phase}  no log activity for ${stallStr}${suffix}\n`;
+        this.stderrWrite(line);
+    }
+}
+/** Convenience factory mirroring `phaseSpinner()`. */
+export function livenessHeartbeat(options) {
+    return new LivenessHeartbeat(options);
+}

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

@@ -8,10 +8,38 @@
  * is agent-agnostic.
  */
 import { ShutdownManager } from "../shutdown.js";
-import { PhaseSpinner } from "../phase-spinner.js";
+/**
+ * Lifecycle hook for pausing the run renderer's live zone while verbose
+ * Claude streaming writes through stdout, then resuming after the agent
+ * call completes. Replaces the legacy `PhaseSpinner` argument (#618).
+ */
+export interface PhasePauseHandle {
+    pause(): void;
+    resume(): void;
+}
 import { Phase, ExecutionConfig, PhaseResult, QaVerdict } from "./types.js";
 import type { QaSummary } from "./run-log-schema.js";
 import type { AgentPhaseResult } from "./drivers/index.js";
+/**
+ * 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 declare function createThrottledReporter(fn: (text: string) => void, intervalMs: number): {
+    report(text: string): void;
+    cancel(): void;
+};
 /**
  * Spec-specific retry configuration.
  * Spec failures have a higher failure rate (~8.6%) than other phases due to
@@ -41,17 +69,43 @@ export declare function parseQaSummary(output: string): QaSummary | null;
  * Format duration in human-readable format
  */
 export declare function formatDuration(seconds: number): string;
+/**
+ * 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 declare function resolveBaseRef(cwd: string): string;
 /**
  * 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.
  *
@@ -83,7 +137,7 @@ export declare function getPhasePrompt(phase: Phase, issueNumber: number, agent?
 /**
  * Execute a single phase for an issue using the configured AgentDriver.
  */
-declare function executePhase(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhaseSpinner): Promise<PhaseResult & {
+declare function executePhase(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle): Promise<PhaseResult & {
     sessionId?: string;
 }>;
 /**
@@ -100,7 +154,7 @@ declare function executePhase(issueNumber: number, phase: Phase, config: Executi
 /**
  * @internal Exported for testing only
  */
-export declare function executePhaseWithRetry(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhaseSpinner, 
+export declare function executePhaseWithRetry(issueNumber: number, phase: Phase, config: ExecutionConfig, sessionId?: string, worktreePath?: string, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle, 
 /** @internal Injected for testing — defaults to module-level executePhase */
 executePhaseFn?: typeof executePhase, 
 /** @internal Injected for testing — defaults to setTimeout-based delay */

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

@@ -8,7 +8,7 @@
  * 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";
@@ -92,6 +92,50 @@ const ISOLATED_PHASES = [
  */
 const COLD_START_THRESHOLD_SECONDS = 60;
 const COLD_START_MAX_RETRIES = 2;
+/**
+ * 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.
  * Spec failures have a higher failure rate (~8.6%) than other phases due to
@@ -218,29 +262,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 +349,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;
@@ -460,11 +561,44 @@ 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;
+    // 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;
     // 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
@@ -481,13 +615,16 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         mcp: config.mcp,
         sessionId: canResume ? sessionId : undefined,
         files,
-        onOutput: config.verbose
+        onOutput: config.verbose || reportActivity
             ? (text) => {
-                if (!verboseStreamingActive) {
-                    spinner?.pause();
-                    verboseStreamingActive = true;
+                if (config.verbose) {
+                    if (!verboseStreamingActive) {
+                        spinner?.pause();
+                        verboseStreamingActive = true;
+                    }
+                    process.stdout.write(chalk.gray(text));
                 }
-                process.stdout.write(chalk.gray(text));
+                reportActivity?.(text);
             }
             : undefined,
         onStderr: config.verbose
@@ -505,6 +642,10 @@ async function executePhase(issueNumber, phase, config, sessionId, worktreePath,
         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();

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

@@ -14,17 +14,18 @@ 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)
  */
 export declare const BUG_LABELS: string[];
 /**
- * Documentation labels that skip spec phase
+ * Documentation labels (used for issueType propagation and downstream metadata)
  */
 export declare const DOCS_LABELS: string[];
 /**