sequant 2.9.0 → 2.11.0

package/dist/src/lib/workflow/effort-escalation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Evidence-based effort escalation on quality-loop retries (#915).
+ *
+ * Sequant already detects several "this attempt is a retry" moments: the
+ * outer quality-loop re-entering a phase (`batch-executor.ts`) and the
+ * `sequant ready` QA-pass loop re-running `qa`/`loop` (`ready-gate.ts`).
+ * Escalation raises the phase's reasoning effort one tier for exactly that
+ * retried execution when the workflow observed a prior attempt fail — never
+ * speculatively, and never more than one tier per retry (see AC-6).
+ *
+ * Deliberately its own module rather than living beside `resolvePhasePolicies`
+ * in `config-resolver.ts`: `config-resolver.ts` imports `getEnvConfig` from
+ * `batch-executor.ts`, and `batch-executor.ts` is one of this module's
+ * dispatch-time callers, so co-locating here avoids introducing that cycle.
+ */
+import { EFFORT_LEVELS } from "../settings.js";
+import type { ExecutionConfig, Phase } from "./types.js";
+/**
+ * Base effort assumed for a phase with no configured `effort` override, when
+ * escalation needs a starting point to step up from (AC-5). `phase-executor.ts`
+ * omits the `effort` key entirely in that case (#914) so the Agent SDK's own
+ * default applies — #914 deliberately never encoded what that default is,
+ * since "omitted" is not the same claim as "equals X".
+ *
+ * Verified against `@anthropic-ai/claude-agent-sdk`'s own `query()` Options
+ * type (`sdk.d.ts`): `effort?: EffortLevel` is documented inline as
+ * `'high' — Deep reasoning (default)`. That is the SDK's default for the
+ * exact call sequant makes (raw `query()`, not the Claude Code CLI product —
+ * whose own `xhigh` default is a caller choice on top of this SDK, not the
+ * SDK's own default), so this constant is not a guess.
+ */
+export declare const DEFAULT_ESCALATION_BASE: (typeof EFFORT_LEVELS)[number];
+/**
+ * Pure ladder step: one tier above `base` on `EFFORT_LEVELS`, capped at the
+ * top (`max`). Returns `base` unchanged whenever `enabled` is false or this
+ * isn't a retry — the disabled/first-attempt path must be indistinguishable
+ * from #914 with escalation never having existed (AC-2).
+ *
+ * Always escalates from the phase's CONFIGURED base, never from a previously
+ * escalated value — callers must not accumulate escalation across iterations
+ * (AC-6): base `high` on the 3rd loop iteration is `xhigh`, not `max`.
+ */
+export declare function resolveEscalatedEffort(base: string | undefined, isRetry: boolean, enabled: boolean): string | undefined;
+/** One escalated execution, for observability (run metrics + verbose output). */
+export interface EscalationRecord {
+    phase: Phase;
+    base: string;
+    escalated: string;
+}
+export interface EscalationOutcome {
+    /**
+     * The config to dispatch with. Identical by reference to the input `config`
+     * whenever nothing escalated — so a shared `ExecutionConfig` object is never
+     * mutated and an escalation never leaks into a phase execution it wasn't
+     * computed for (AC-7).
+     */
+    config: ExecutionConfig;
+    /** Present only when this dispatch actually escalated. */
+    record?: EscalationRecord;
+}
+/**
+ * Apply escalation to ONE phase's execution, for THIS dispatch only.
+ *
+ * This is deliberately a per-execution decision made at the dispatch site,
+ * not a value baked into `ExecutionConfig` at build time: `buildExecutionConfig`
+ * / `buildPhaseConfig` run once per run/gate, not once per phase execution, so
+ * a static escalated value would leak across every phase in the chain and
+ * violate AC-7. The three retry-dispatch sites (batch-executor.ts's quality
+ * loop, ready-gate.ts's QA-pass loop `qa`/`loop` dispatch) call this function
+ * — and only this function — so they cannot drift on the cap/one-tier rules
+ * in AC-6 (see resolveEscalatedEffort's doc comment).
+ */
+export declare function withEscalatedEffort(config: ExecutionConfig, phase: Phase, isRetry: boolean): EscalationOutcome;

package/dist/src/lib/workflow/effort-escalation.js

@@ -0,0 +1,82 @@
+/**
+ * Evidence-based effort escalation on quality-loop retries (#915).
+ *
+ * Sequant already detects several "this attempt is a retry" moments: the
+ * outer quality-loop re-entering a phase (`batch-executor.ts`) and the
+ * `sequant ready` QA-pass loop re-running `qa`/`loop` (`ready-gate.ts`).
+ * Escalation raises the phase's reasoning effort one tier for exactly that
+ * retried execution when the workflow observed a prior attempt fail — never
+ * speculatively, and never more than one tier per retry (see AC-6).
+ *
+ * Deliberately its own module rather than living beside `resolvePhasePolicies`
+ * in `config-resolver.ts`: `config-resolver.ts` imports `getEnvConfig` from
+ * `batch-executor.ts`, and `batch-executor.ts` is one of this module's
+ * dispatch-time callers, so co-locating here avoids introducing that cycle.
+ */
+import { EFFORT_LEVELS } from "../settings.js";
+/**
+ * Base effort assumed for a phase with no configured `effort` override, when
+ * escalation needs a starting point to step up from (AC-5). `phase-executor.ts`
+ * omits the `effort` key entirely in that case (#914) so the Agent SDK's own
+ * default applies — #914 deliberately never encoded what that default is,
+ * since "omitted" is not the same claim as "equals X".
+ *
+ * Verified against `@anthropic-ai/claude-agent-sdk`'s own `query()` Options
+ * type (`sdk.d.ts`): `effort?: EffortLevel` is documented inline as
+ * `'high' — Deep reasoning (default)`. That is the SDK's default for the
+ * exact call sequant makes (raw `query()`, not the Claude Code CLI product —
+ * whose own `xhigh` default is a caller choice on top of this SDK, not the
+ * SDK's own default), so this constant is not a guess.
+ */
+export const DEFAULT_ESCALATION_BASE = "high";
+/**
+ * Pure ladder step: one tier above `base` on `EFFORT_LEVELS`, capped at the
+ * top (`max`). Returns `base` unchanged whenever `enabled` is false or this
+ * isn't a retry — the disabled/first-attempt path must be indistinguishable
+ * from #914 with escalation never having existed (AC-2).
+ *
+ * Always escalates from the phase's CONFIGURED base, never from a previously
+ * escalated value — callers must not accumulate escalation across iterations
+ * (AC-6): base `high` on the 3rd loop iteration is `xhigh`, not `max`.
+ */
+export function resolveEscalatedEffort(base, isRetry, enabled) {
+    if (!enabled || !isRetry)
+        return base;
+    const effectiveBase = (base ??
+        DEFAULT_ESCALATION_BASE);
+    const baseIdx = EFFORT_LEVELS.indexOf(effectiveBase);
+    const resolvedIdx = baseIdx === -1 ? EFFORT_LEVELS.indexOf(DEFAULT_ESCALATION_BASE) : baseIdx;
+    const nextIdx = Math.min(resolvedIdx + 1, EFFORT_LEVELS.length - 1);
+    return EFFORT_LEVELS[nextIdx];
+}
+/**
+ * Apply escalation to ONE phase's execution, for THIS dispatch only.
+ *
+ * This is deliberately a per-execution decision made at the dispatch site,
+ * not a value baked into `ExecutionConfig` at build time: `buildExecutionConfig`
+ * / `buildPhaseConfig` run once per run/gate, not once per phase execution, so
+ * a static escalated value would leak across every phase in the chain and
+ * violate AC-7. The three retry-dispatch sites (batch-executor.ts's quality
+ * loop, ready-gate.ts's QA-pass loop `qa`/`loop` dispatch) call this function
+ * — and only this function — so they cannot drift on the cap/one-tier rules
+ * in AC-6 (see resolveEscalatedEffort's doc comment).
+ */
+export function withEscalatedEffort(config, phase, isRetry) {
+    if (!config.effortEscalation || !isRetry)
+        return { config };
+    const currentPolicy = config.phasePolicies?.[phase];
+    const base = currentPolicy?.effort;
+    const escalated = resolveEscalatedEffort(base, isRetry, true);
+    if (!escalated || escalated === base)
+        return { config };
+    return {
+        config: {
+            ...config,
+            phasePolicies: {
+                ...config.phasePolicies,
+                [phase]: { ...currentPolicy, effort: escalated },
+            },
+        },
+        record: { phase, base: base ?? DEFAULT_ESCALATION_BASE, escalated },
+    };
+}

package/dist/src/lib/workflow/error-classifier.d.ts

@@ -11,9 +11,12 @@ import { SequantError } from "../errors.js";
  * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
  * errors — `classifyError` never produces them, since stderr text cannot
  * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * `pr_creation` (#920) is assigned only at the `deriveFailureCategory` call
+ * site, not by `classifyError` — a failed `createPR` has no failing phase to
+ * classify, so it would otherwise leave `failureCategory` `undefined`.
  * Keep in sync with the inline category enum in `run-log-schema.ts`.
  */
-export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "rate_limit", "billing", "unknown"];
+export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "rate_limit", "billing", "pr_creation", "unknown"];
 export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
 /**
  * Map from error type name to legacy category string.

package/dist/src/lib/workflow/error-classifier.js

@@ -11,6 +11,9 @@ import { ContextOverflowError, ApiError, HookFailureError, BuildError, TimeoutEr
  * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
  * errors — `classifyError` never produces them, since stderr text cannot
  * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * `pr_creation` (#920) is assigned only at the `deriveFailureCategory` call
+ * site, not by `classifyError` — a failed `createPR` has no failing phase to
+ * classify, so it would otherwise leave `failureCategory` `undefined`.
  * Keep in sync with the inline category enum in `run-log-schema.ts`.
  */
 export const ERROR_CATEGORIES = [
@@ -21,6 +24,7 @@ export const ERROR_CATEGORIES = [
     "timeout",
     "rate_limit",
     "billing",
+    "pr_creation",
     "unknown",
 ];
 /**

package/dist/src/lib/workflow/git-diff-utils.d.ts

@@ -18,18 +18,50 @@ export interface GitDiffStatsResult {
     /** Total lines deleted across all files */
     totalDeletions: number;
 }
+/**
+ * Resolve the ref diff stats should compare against (#878).
+ *
+ * Worktrees are created from `origin/<base>` (worktree-manager), but callers
+ * historically passed the bare branch name and the diff ran against the
+ * *local* ref. When local `<base>` lags the remote — routine, since nothing
+ * in the run path updates it — `<base>...HEAD` attributes commits the run
+ * never made (phantom filesModified).
+ *
+ * Candidates are the origin-qualified and bare forms of `baseBranch`
+ * (already-remote-qualified input keeps a single candidate). Among the
+ * candidates that resolve to a commit, pick the one nearest to HEAD
+ * (smallest `rev-list --count <cand>..HEAD`), preferring the
+ * origin-qualified form on a tie. Nearest-wins matches the worktree's
+ * actual creation point in both staleness directions: a stale local
+ * default branch (this issue) and a chain-mode worktree branched from a
+ * local base that is ahead of its pushed counterpart. Falls back to
+ * `baseBranch` verbatim when no candidate resolves (e.g. remote-less repo
+ * with a missing branch) — the diff then fails gracefully to empty, the
+ * pre-#878 behavior.
+ */
+export declare function resolveDiffBase(worktreePath: string, baseBranch: string): string;
 /**
  * Get git commit SHA for a worktree (AC-2)
  *
+ * When `baseRef` is provided, returns undefined if HEAD has no commits
+ * unique to it (#878) — a branch that never moved off its base would
+ * otherwise log the base tip as if it were the phase's commit. Callers
+ * recording plain "where is HEAD" markers (run start/end) omit `baseRef`.
+ *
  * @param worktreePath - Path to the git worktree
- * @returns The current HEAD commit SHA, or undefined on error
+ * @param baseRef - Optional resolved base ref (see resolveDiffBase); when
+ *   given, a HEAD with zero commits past it yields undefined
+ * @returns The current HEAD commit SHA, or undefined on error / no unique
+ *   commits
  */
-export declare function getCommitHash(worktreePath: string): string | undefined;
+export declare function getCommitHash(worktreePath: string, baseRef?: string): string | undefined;
 /**
  * Get git diff statistics for a worktree (AC-1, AC-3, AC-4)
  *
  * Efficiently captures both filesModified and fileDiffStats using
- * minimal git commands. Uses main...HEAD comparison by default.
+ * minimal git commands. The base is resolved via resolveDiffBase (#878) so
+ * the comparison targets the ref the worktree was actually created from
+ * (origin/<base> in the common case) rather than a possibly-stale local ref.
  *
  * @param worktreePath - Path to the git worktree
  * @param baseBranch - Branch to compare against (default: "main")

package/dist/src/lib/workflow/git-diff-utils.js

@@ -73,13 +73,73 @@ function parseNameStatus(output) {
     }
     return result;
 }
+/**
+ * Resolve the ref diff stats should compare against (#878).
+ *
+ * Worktrees are created from `origin/<base>` (worktree-manager), but callers
+ * historically passed the bare branch name and the diff ran against the
+ * *local* ref. When local `<base>` lags the remote — routine, since nothing
+ * in the run path updates it — `<base>...HEAD` attributes commits the run
+ * never made (phantom filesModified).
+ *
+ * Candidates are the origin-qualified and bare forms of `baseBranch`
+ * (already-remote-qualified input keeps a single candidate). Among the
+ * candidates that resolve to a commit, pick the one nearest to HEAD
+ * (smallest `rev-list --count <cand>..HEAD`), preferring the
+ * origin-qualified form on a tie. Nearest-wins matches the worktree's
+ * actual creation point in both staleness directions: a stale local
+ * default branch (this issue) and a chain-mode worktree branched from a
+ * local base that is ahead of its pushed counterpart. Falls back to
+ * `baseBranch` verbatim when no candidate resolves (e.g. remote-less repo
+ * with a missing branch) — the diff then fails gracefully to empty, the
+ * pre-#878 behavior.
+ */
+export function resolveDiffBase(worktreePath, baseBranch) {
+    const candidates = baseBranch.startsWith("origin/")
+        ? [baseBranch]
+        : [`origin/${baseBranch}`, baseBranch];
+    let best;
+    let bestCount = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const verify = spawnSync("git", [
+            "-C",
+            worktreePath,
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `${candidate}^{commit}`,
+        ], { stdio: "pipe", encoding: "utf-8" });
+        if (verify.status !== 0)
+            continue;
+        const count = spawnSync("git", ["-C", worktreePath, "rev-list", "--count", `${candidate}..HEAD`], { stdio: "pipe", encoding: "utf-8" });
+        if (count.status !== 0)
+            continue;
+        const n = Number.parseInt(count.stdout.trim(), 10);
+        if (Number.isNaN(n))
+            continue;
+        // Strict < keeps the earlier (origin-qualified) candidate on a tie.
+        if (n < bestCount) {
+            best = candidate;
+            bestCount = n;
+        }
+    }
+    return best ?? baseBranch;
+}
 /**
  * Get git commit SHA for a worktree (AC-2)
  *
+ * When `baseRef` is provided, returns undefined if HEAD has no commits
+ * unique to it (#878) — a branch that never moved off its base would
+ * otherwise log the base tip as if it were the phase's commit. Callers
+ * recording plain "where is HEAD" markers (run start/end) omit `baseRef`.
+ *
  * @param worktreePath - Path to the git worktree
- * @returns The current HEAD commit SHA, or undefined on error
+ * @param baseRef - Optional resolved base ref (see resolveDiffBase); when
+ *   given, a HEAD with zero commits past it yields undefined
+ * @returns The current HEAD commit SHA, or undefined on error / no unique
+ *   commits
  */
-export function getCommitHash(worktreePath) {
+export function getCommitHash(worktreePath, baseRef) {
     const result = spawnSync("git", ["-C", worktreePath, "rev-parse", "HEAD"], {
         stdio: "pipe",
         encoding: "utf-8",
@@ -87,20 +147,33 @@ export function getCommitHash(worktreePath) {
     if (result.status !== 0) {
         return undefined;
     }
+    if (baseRef !== undefined) {
+        const count = spawnSync("git", ["-C", worktreePath, "rev-list", "--count", `${baseRef}..HEAD`], { stdio: "pipe", encoding: "utf-8" });
+        // Fail open on git errors: a transient failure should not erase a real
+        // commit hash from the log — only a confirmed zero suppresses it.
+        if (count.status === 0) {
+            const n = Number.parseInt(count.stdout.trim(), 10);
+            if (n === 0) {
+                return undefined;
+            }
+        }
+    }
     return result.stdout.trim();
 }
 /**
  * Get git diff statistics for a worktree (AC-1, AC-3, AC-4)
  *
  * Efficiently captures both filesModified and fileDiffStats using
- * minimal git commands. Uses main...HEAD comparison by default.
+ * minimal git commands. The base is resolved via resolveDiffBase (#878) so
+ * the comparison targets the ref the worktree was actually created from
+ * (origin/<base> in the common case) rather than a possibly-stale local ref.
  *
  * @param worktreePath - Path to the git worktree
  * @param baseBranch - Branch to compare against (default: "main")
  * @returns GitDiffStatsResult with files, stats, and totals
  */
 export function getGitDiffStats(worktreePath, baseBranch = "main") {
-    const diffRef = `${baseBranch}...HEAD`;
+    const diffRef = `${resolveDiffBase(worktreePath, baseBranch)}...HEAD`;
     // Get numstat for additions/deletions
     const numstatResult = spawnSync("git", ["-C", worktreePath, "diff", "--numstat", diffRef], { stdio: "pipe", encoding: "utf-8" });
     // Get name-status for file status (added/modified/deleted/renamed)

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

@@ -1,4 +1,13 @@
 import type { ShutdownManager } from "../shutdown.js";
+/**
+ * Cadence of the non-TTY auto-wait notice (#860 AC-6). Non-TTY output is
+ * append-only (no `\r` rewrite), so the TTY heartbeat's every-tick refresh
+ * would log ~600 lines over a five-hour wait. Five minutes keeps an unattended
+ * log legibly alive (~60 lines per five-hour window) without drowning it.
+ *
+ * @internal Exported for testing only
+ */
+export declare const NON_TTY_WAIT_NOTICE_INTERVAL_MS: number;
 export interface LivenessHeartbeatOptions {
     /** Polling cadence for heartbeat ticks. Default: 30_000ms */
     pollIntervalMs?: number;
@@ -60,10 +69,39 @@ export declare class LivenessHeartbeat {
      * Dispose all tracked phases and clear the timer. Idempotent.
      */
     dispose(): void;
+    /**
+     * Mark a phase as auto-waiting for a rate-limit window to reopen (#804 AC-7).
+     *
+     * This is not cosmetic. The stall detector's activity proxy is the mtime of
+     * `.sequant/state.json`, and an auto-wait produces no writes by definition —
+     * so a multi-hour wait would otherwise trip the "no log activity" warning
+     * within minutes and report an entirely expected pause as a stall. Marking
+     * the phase both relabels the heartbeat line with the wake time and
+     * suppresses that false warning.
+     *
+     * No-op for an untracked phase, so an out-of-order or late notice cannot
+     * resurrect a stopped entry.
+     */
+    pauseForWait(key: PhaseKey, wakeAtMs: number): void;
+    /** Clear the auto-wait marker set by {@link pauseForWait} (#804). */
+    resumeFromWait(key: PhaseKey): void;
     /** Test hook: drive a poll synchronously without waiting on real timers. */
     tickNow(): void;
     private tick;
     private writeHeartbeat;
+    /**
+     * Heartbeat line for a phase paused on an auto-wait (#804). Names the wake
+     * time and the remaining wait so a multi-hour pause is legibly deliberate
+     * rather than indistinguishable from a hang.
+     */
+    private writeWaitHeartbeat;
+    /**
+     * Append-only auto-wait notice for non-TTY runs (#860 AC-6). Same facts as
+     * {@link writeWaitHeartbeat} — wake time and remaining wait — but a plain
+     * `\n`-terminated line with no cursor control, throttled by the caller to
+     * {@link NON_TTY_WAIT_NOTICE_INTERVAL_MS} so an unattended log stays legible.
+     */
+    private writeNonTtyWaitNotice;
     private writeStallWarning;
 }
 /** Convenience factory mirroring `phaseSpinner()`. */

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

@@ -12,10 +12,20 @@
  */
 import * as fs from "fs";
 import { formatElapsedTime } from "../cli-ui/format.js";
+import { formatResetTime } from "../errors.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";
+/**
+ * Cadence of the non-TTY auto-wait notice (#860 AC-6). Non-TTY output is
+ * append-only (no `\r` rewrite), so the TTY heartbeat's every-tick refresh
+ * would log ~600 lines over a five-hour wait. Five minutes keeps an unattended
+ * log legibly alive (~60 lines per five-hour window) without drowning it.
+ *
+ * @internal Exported for testing only
+ */
+export const NON_TTY_WAIT_NOTICE_INTERVAL_MS = 5 * 60_000;
 function keyFor(k) {
     return `${k.issueNumber}:${k.phase}`;
 }
@@ -118,6 +128,39 @@ export class LivenessHeartbeat {
             this.cleanupRegistered = false;
         }
     }
+    /**
+     * Mark a phase as auto-waiting for a rate-limit window to reopen (#804 AC-7).
+     *
+     * This is not cosmetic. The stall detector's activity proxy is the mtime of
+     * `.sequant/state.json`, and an auto-wait produces no writes by definition —
+     * so a multi-hour wait would otherwise trip the "no log activity" warning
+     * within minutes and report an entirely expected pause as a stall. Marking
+     * the phase both relabels the heartbeat line with the wake time and
+     * suppresses that false warning.
+     *
+     * No-op for an untracked phase, so an out-of-order or late notice cannot
+     * resurrect a stopped entry.
+     */
+    pauseForWait(key, wakeAtMs) {
+        const entry = this.phases.get(keyFor(key));
+        if (!entry)
+            return;
+        entry.waitingUntil = wakeAtMs;
+        // Clear any warning already fired so a genuine stall after the wait can
+        // still warn once.
+        entry.warningFired = false;
+        // #860 AC-6: a fresh wait announces itself on the next non-TTY tick.
+        entry.lastWaitNoticeAt = undefined;
+    }
+    /** Clear the auto-wait marker set by {@link pauseForWait} (#804). */
+    resumeFromWait(key) {
+        const entry = this.phases.get(keyFor(key));
+        if (!entry)
+            return;
+        entry.waitingUntil = undefined;
+        entry.warningFired = false;
+        entry.lastWaitNoticeAt = undefined;
+    }
     /** Test hook: drive a poll synchronously without waiting on real timers. */
     tickNow() {
         this.tick();
@@ -127,6 +170,23 @@ export class LivenessHeartbeat {
             return;
         const now = this.now();
         for (const entry of this.phases.values()) {
+            // #804: an auto-waiting phase has its own liveness story. Handled before
+            // the mtime read because the wait produces no file activity at all — the
+            // stall detector's proxy is meaningless here, and the `mtimeMs === null`
+            // early-continue below would otherwise leave the wait completely silent.
+            if (entry.waitingUntil !== undefined) {
+                if (this.tty) {
+                    this.writeWaitHeartbeat(entry, Math.max(0, now - entry.startedAt));
+                }
+                else if (entry.lastWaitNoticeAt === undefined ||
+                    now - entry.lastWaitNoticeAt >= NON_TTY_WAIT_NOTICE_INTERVAL_MS) {
+                    // #860 AC-6: without this, a non-TTY wait emits nothing for hours —
+                    // indistinguishable from the #856 hang. Append-only line, throttled.
+                    this.writeNonTtyWaitNotice(entry);
+                    entry.lastWaitNoticeAt = now;
+                }
+                continue;
+            }
             let mtimeMs;
             try {
                 const stat = fs.statSync(this.livenessFile);
@@ -168,6 +228,36 @@ export class LivenessHeartbeat {
         const line = `\r  ▸ #${entry.issueNumber}  ${entry.phase}  (${elapsed} elapsed, last log update ${sinceActivity} ago)`;
         this.stdoutWrite(line);
     }
+    /**
+     * Heartbeat line for a phase paused on an auto-wait (#804). Names the wake
+     * time and the remaining wait so a multi-hour pause is legibly deliberate
+     * rather than indistinguishable from a hang.
+     */
+    writeWaitHeartbeat(entry, elapsedSinceStartMs) {
+        if (this.stopped || entry.waitingUntil === undefined)
+            return;
+        const elapsed = formatElapsedTime(Math.floor(elapsedSinceStartMs / 1000));
+        const remainingMs = Math.max(0, entry.waitingUntil - this.now());
+        const remaining = formatElapsedTime(Math.floor(remainingMs / 1000));
+        const wake = formatResetTime(entry.waitingUntil);
+        const line = `\r  ⏸ #${entry.issueNumber}  ${entry.phase}  (${elapsed} elapsed, rate-limit window — resuming at ${wake}, ${remaining} left)\x1b[K`;
+        this.stdoutWrite(line);
+    }
+    /**
+     * Append-only auto-wait notice for non-TTY runs (#860 AC-6). Same facts as
+     * {@link writeWaitHeartbeat} — wake time and remaining wait — but a plain
+     * `\n`-terminated line with no cursor control, throttled by the caller to
+     * {@link NON_TTY_WAIT_NOTICE_INTERVAL_MS} so an unattended log stays legible.
+     */
+    writeNonTtyWaitNotice(entry) {
+        if (this.stopped || entry.waitingUntil === undefined)
+            return;
+        const remainingMs = Math.max(0, entry.waitingUntil - this.now());
+        const remaining = formatElapsedTime(Math.floor(remainingMs / 1000));
+        const wake = formatResetTime(entry.waitingUntil);
+        const line = `  ⏸ #${entry.issueNumber}  ${entry.phase}  rate-limit window — resuming at ${wake} (${remaining} left)\n`;
+        this.stdoutWrite(line);
+    }
     writeStallWarning(entry, sinceActivityMs, elapsedSinceStartMs) {
         if (this.stopped)
             return;

package/dist/src/lib/workflow/log-writer.d.ts

@@ -13,7 +13,7 @@
  * await writer.finalize();
  * ```
  */
-import { type RunLog, type RunConfig, type PhaseLog, type Phase } from "./run-log-schema.js";
+import { type RunLog, type RunConfig, type PhaseLog, type Phase, type SpecRecommendation } from "./run-log-schema.js";
 import { type RotationSettings } from "./log-rotation.js";
 export interface LogWriterOptions {
     /** Path to log directory (default: .sequant/logs in current directory) */
@@ -26,6 +26,13 @@ export interface LogWriterOptions {
     rotation?: RotationSettings;
     /** Git commit SHA at run start (AC-2) */
     startCommit?: string;
+    /**
+     * Run start timestamp (#867). When provided, the log's `startTime` uses this
+     * origin instead of self-stamping `new Date()` at initialize(), so the log's
+     * stored wall clock and the orchestrator's summary derive from one shared
+     * start. Defaults to now when omitted.
+     */
+    startTime?: Date;
 }
 /**
  * Manages writing structured run logs to disk
@@ -36,11 +43,20 @@ export declare class LogWriter {
     private activeIssues;
     /** @deprecated Single-issue slot for backwards compatibility — use activeIssues */
     private currentIssue;
+    /**
+     * Issue slots forced to `failure` by {@link markIssueFailed} (#879). Keyed on
+     * the slot object so it covers both the numbered and legacy `currentIssue`
+     * paths. `completeIssue` re-derives status from phases (#856), so a seeded
+     * `issue.status = "failure"` alone would be overwritten back to `success`;
+     * this marker survives that re-derivation.
+     */
+    private forcedFailures;
     private logPath;
     private writeToUserLogs;
     private verbose;
     private rotation;
     private startCommit?;
+    private startTime?;
     constructor(options?: LogWriterOptions);
     /**
      * Initialize a new run log
@@ -66,10 +82,37 @@ export declare class LogWriter {
      * Set PR info on the current issue (call before completeIssue)
      */
     setPRInfo(prNumber: number, prUrl: string, issueNumber?: number): void;
+    /**
+     * Record how the spec→run phase recommendation was resolved (#921 AC-4).
+     *
+     * Called right after `resolveSpecRecommendation` runs, before the next
+     * phase starts — mirrors {@link setPRInfo}'s post-hoc-setter shape because
+     * the spec `PhaseLog` is already written by the time resolution (which does
+     * its own comment-fetch I/O) completes.
+     */
+    setSpecRecommendation(recommendation: SpecRecommendation, issueNumber?: number): void;
+    /**
+     * Force the in-flight issue's status to `failure` (#879).
+     *
+     * `deriveIssueLogStatus` runs at phase-log time, so an issue whose phases all
+     * passed but whose PR creation then failed would otherwise be recorded as
+     * `success`. Call this after the last phase is logged and before
+     * {@link completeIssue} to count it under `failed`. No-op if the issue is not
+     * active. Reuses the existing `failure` enum — no schema change.
+     */
+    markIssueFailed(issueNumber?: number): void;
     /**
      * Complete the current issue and add it to the run log
+     *
+     * @param issueNumber - Issue to complete (defaults to the legacy single slot)
+     * @param abort - Set when the run is being torn down by an external signal
+     *   (#856). Marks the issue aborted with its cause instead of persisting
+     *   whatever verdict the incomplete phase list happens to imply.
      */
-    completeIssue(issueNumber?: number): void;
+    completeIssue(issueNumber?: number, abort?: {
+        signal: string;
+        reason: string;
+    }): void;
     /**
      * Finalize the run log and write to disk
      *
@@ -77,10 +120,19 @@ export declare class LogWriter {
      *
      * @param options - Optional finalization options
      * @param options.endCommit - Git commit SHA at run end (AC-2)
+     * @param options.aborted - Set when finalizing because the run was
+     *   terminated by an external signal (#856). Every still-in-flight issue is
+     *   recorded as an abort naming its cause, and the run log carries
+     *   `abortedBy`. Without it, a killed run's log is indistinguishable from a
+     *   clean one that happened to do nothing.
      * @returns Path to the written log file
      */
     finalize(options?: {
         endCommit?: string;
+        aborted?: {
+            signal: string;
+            reason: string;
+        };
     }): Promise<string>;
     /**
      * Get the current run log (for inspection)