sequant 2.8.0 → 2.10.0

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

@@ -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,28 @@ export declare class LogWriter {
      * Set PR info on the current issue (call before completeIssue)
      */
     setPRInfo(prNumber: number, prUrl: string, 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 +111,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)

package/dist/src/lib/workflow/log-writer.js

@@ -16,7 +16,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { createEmptyRunLog, finalizeRunLog, generateLogFilename, LOG_PATHS, } from "./run-log-schema.js";
+import { createEmptyRunLog, finalizeRunLog, deriveIssueLogStatus, generateLogFilename, LOG_PATHS, } from "./run-log-schema.js";
 import { rotateIfNeeded, DEFAULT_ROTATION_SETTINGS, } from "./log-rotation.js";
 /**
  * Manages writing structured run logs to disk
@@ -27,17 +27,27 @@ export class LogWriter {
     activeIssues = new Map();
     /** @deprecated Single-issue slot for backwards compatibility — use activeIssues */
     currentIssue = null;
+    /**
+     * 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.
+     */
+    forcedFailures = new WeakSet();
     logPath;
     writeToUserLogs;
     verbose;
     rotation;
     startCommit;
+    startTime;
     constructor(options = {}) {
         this.logPath = options.logPath ?? LOG_PATHS.project;
         this.writeToUserLogs = options.writeToUserLogs ?? false;
         this.verbose = options.verbose ?? false;
         this.rotation = options.rotation ?? DEFAULT_ROTATION_SETTINGS;
         this.startCommit = options.startCommit;
+        this.startTime = options.startTime;
     }
     /**
      * Initialize a new run log
@@ -45,7 +55,10 @@ export class LogWriter {
      * @param config - Run configuration
      */
     async initialize(config) {
-        this.runLog = createEmptyRunLog(config, { startCommit: this.startCommit });
+        this.runLog = createEmptyRunLog(config, {
+            startCommit: this.startCommit,
+            startTime: this.startTime,
+        });
         // Ensure log directory exists
         await this.ensureLogDirectory(this.logPath);
         if (this.writeToUserLogs) {
@@ -67,12 +80,17 @@ export class LogWriter {
         if (!this.runLog) {
             throw new Error("LogWriter not initialized. Call initialize() first.");
         }
+        // #856: seed pessimistically. This slot is only revised by `logPhase`, so
+        // an optimistic `"success"` seed became the persisted verdict for any
+        // issue whose first phase never completed — the exact shape of a run
+        // killed mid-flight. `completeIssue` re-derives from `phases` regardless,
+        // but the seed should not itself assert a pass that never happened.
         const issueData = {
             issueNumber,
             title,
             labels,
             phases: [],
-            status: "success",
+            status: "failure",
             totalDurationSeconds: 0,
         };
         this.activeIssues.set(issueNumber, issueData);
@@ -94,13 +112,11 @@ export class LogWriter {
             throw new Error(`No active issue #${phaseLog.issueNumber}. Call startIssue() first.`);
         }
         issue.phases = [...(issue.phases ?? []), phaseLog];
-        // Update issue status based on phase result
-        if (phaseLog.status === "failure") {
-            issue.status = "failure";
-        }
-        else if (phaseLog.status === "timeout" && issue.status !== "failure") {
-            issue.status = "partial";
-        }
+        // #766: derive from the latest attempt of each phase (loop excluded) rather
+        // than pinning failure/partial forever. A timeout or failure that a later
+        // quality-loop iteration recovers from no longer sticks, so the JSON log
+        // agrees with the live card and summary table (AC-3/AC-5).
+        issue.status = deriveIssueLogStatus(issue.phases);
         if (this.verbose) {
             console.log(`Log phase: ${phaseLog.phase} (${phaseLog.status}) - ${phaseLog.durationSeconds.toFixed(1)}s`);
         }
@@ -118,10 +134,36 @@ export class LogWriter {
         issue.prNumber = prNumber;
         issue.prUrl = prUrl;
     }
+    /**
+     * 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) {
+        const issue = issueNumber
+            ? (this.activeIssues.get(issueNumber) ?? this.currentIssue)
+            : this.currentIssue;
+        if (!issue) {
+            return;
+        }
+        issue.status = "failure";
+        // completeIssue re-derives status from the phase list (#856), so the seed
+        // above is not enough on its own — mark the slot so completion honors it.
+        this.forcedFailures.add(issue);
+    }
     /**
      * 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) {
+    completeIssue(issueNumber, abort) {
         if (!this.runLog) {
             throw new Error("No run log. Call initialize() first.");
         }
@@ -136,13 +178,31 @@ export class LogWriter {
         }
         // Calculate total duration from phases
         const totalDurationSeconds = issue.phases?.reduce((sum, p) => sum + p.durationSeconds, 0) ?? 0;
+        // #856: derive from the phase list rather than trusting the slot's seed.
+        // An issue with no completed phase is a failure — the run was cut short.
+        //
+        // An abort forces `failure` even when every phase logged so far passed:
+        // the issue was still in flight when the signal arrived, so its pipeline
+        // never reached a terminal state and a partial prefix of green phases is
+        // not a pass. `abortReason` records why, so the log names its own cause
+        // instead of leaving a silently truncated record.
+        // #879: markIssueFailed forces `failure` when every phase passed but a
+        // later step (e.g. PR creation) failed — same override intent as `abort`,
+        // so it must win over the phase-derived status too.
+        const status = abort || this.forcedFailures.has(issue)
+            ? "failure"
+            : deriveIssueLogStatus(issue.phases ?? []);
         const issueLog = {
             issueNumber: issue.issueNumber,
             title: issue.title,
             labels: issue.labels,
-            status: issue.status,
+            status,
             phases: issue.phases,
             totalDurationSeconds,
+            ...(abort && {
+                aborted: true,
+                abortReason: abort.reason,
+            }),
             ...(issue.prNumber != null && {
                 prNumber: issue.prNumber,
             }),
@@ -170,22 +230,29 @@ export 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
      */
     async finalize(options) {
         if (!this.runLog) {
             throw new Error("LogWriter not initialized.");
         }
+        const abort = options?.aborted;
         // Complete any pending issues (Map-based concurrent tracking)
         for (const issueNum of [...this.activeIssues.keys()]) {
-            this.completeIssue(issueNum);
+            this.completeIssue(issueNum, abort);
         }
         // Fallback: complete legacy currentIssue if not already handled
         if (this.currentIssue) {
-            this.completeIssue();
+            this.completeIssue(undefined, abort);
         }
         const finalLog = finalizeRunLog(this.runLog, {
             endCommit: options?.endCommit,
+            abortedBy: abort?.signal,
         });
         const filename = generateLogFilename(finalLog.runId, new Date(finalLog.startTime));
         // Write to project logs

package/dist/src/lib/workflow/metrics-schema.d.ts

@@ -25,15 +25,33 @@ export declare const RunOutcomeSchema: z.ZodEnum<{
     failed: "failed";
 }>;
 export type RunOutcome = z.infer<typeof RunOutcomeSchema>;
+/**
+ * Bounded-enum classification of the failure that ended a run (#761 AC-7).
+ *
+ * Sourced from `ERROR_CATEGORIES` so the metric can never carry free text —
+ * error *messages* stay excluded per the privacy contract above MetricRunSchema
+ * (they could contain sensitive info); a closed enum cannot.
+ */
+export declare const FailureCategorySchema: z.ZodEnum<{
+    unknown: "unknown";
+    timeout: "timeout";
+    context_overflow: "context_overflow";
+    api_error: "api_error";
+    hook_failure: "hook_failure";
+    build_error: "build_error";
+    rate_limit: "rate_limit";
+    billing: "billing";
+}>;
+export type FailureCategory = z.infer<typeof FailureCategorySchema>;
 /**
  * Available phases (aligned with run-log-schema.ts)
  */
 export declare const MetricPhaseSchema: z.ZodEnum<{
+    exec: "exec";
     qa: "qa";
     loop: "loop";
     spec: "spec";
     "security-review": "security-review";
-    exec: "exec";
     testgen: "testgen";
     test: "test";
 }>;
@@ -67,11 +85,11 @@ export declare const MetricRunSchema: z.ZodObject<{
     date: z.ZodString;
     issues: z.ZodArray<z.ZodNumber>;
     phases: z.ZodArray<z.ZodEnum<{
+        exec: "exec";
         qa: "qa";
         loop: "loop";
         spec: "spec";
         "security-review": "security-review";
-        exec: "exec";
         testgen: "testgen";
         test: "test";
     }>>;
@@ -83,6 +101,16 @@ export declare const MetricRunSchema: z.ZodObject<{
     duration: z.ZodNumber;
     model: z.ZodString;
     flags: z.ZodArray<z.ZodString>;
+    failureCategory: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        timeout: "timeout";
+        context_overflow: "context_overflow";
+        api_error: "api_error";
+        hook_failure: "hook_failure";
+        build_error: "build_error";
+        rate_limit: "rate_limit";
+        billing: "billing";
+    }>>;
     metrics: z.ZodObject<{
         tokensUsed: z.ZodNumber;
         filesChanged: z.ZodNumber;
@@ -107,11 +135,11 @@ export declare const MetricsSchema: z.ZodObject<{
         date: z.ZodString;
         issues: z.ZodArray<z.ZodNumber>;
         phases: z.ZodArray<z.ZodEnum<{
+            exec: "exec";
             qa: "qa";
             loop: "loop";
             spec: "spec";
             "security-review": "security-review";
-            exec: "exec";
             testgen: "testgen";
             test: "test";
         }>>;
@@ -123,6 +151,16 @@ export declare const MetricsSchema: z.ZodObject<{
         duration: z.ZodNumber;
         model: z.ZodString;
         flags: z.ZodArray<z.ZodString>;
+        failureCategory: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            timeout: "timeout";
+            context_overflow: "context_overflow";
+            api_error: "api_error";
+            hook_failure: "hook_failure";
+            build_error: "build_error";
+            rate_limit: "rate_limit";
+            billing: "billing";
+        }>>;
         metrics: z.ZodObject<{
             tokensUsed: z.ZodNumber;
             filesChanged: z.ZodNumber;
@@ -154,6 +192,7 @@ export declare function createMetricRun(options: {
     duration: number;
     model?: string;
     flags?: string[];
+    failureCategory?: FailureCategory;
     metrics?: Partial<RunMetrics>;
 }): MetricRun;
 /**