sequant 2.9.0 → 2.11.0

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

@@ -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);
@@ -116,10 +134,53 @@ export class LogWriter {
         issue.prNumber = prNumber;
         issue.prUrl = prUrl;
     }
+    /**
+     * 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, issueNumber) {
+        const issue = issueNumber
+            ? (this.activeIssues.get(issueNumber) ?? this.currentIssue)
+            : this.currentIssue;
+        if (!issue) {
+            return;
+        }
+        issue.specRecommendation = recommendation;
+    }
+    /**
+     * 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.");
         }
@@ -134,19 +195,40 @@ 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,
             }),
             ...(issue.prUrl != null && {
                 prUrl: issue.prUrl,
             }),
+            ...(issue.specRecommendation != null && {
+                specRecommendation: issue.specRecommendation,
+            }),
         };
         this.runLog.issues.push(issueLog);
         // Clean up from activeIssues map
@@ -168,22 +250,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

@@ -41,19 +41,20 @@ export declare const FailureCategorySchema: z.ZodEnum<{
     build_error: "build_error";
     rate_limit: "rate_limit";
     billing: "billing";
+    pr_creation: "pr_creation";
 }>;
 export type FailureCategory = z.infer<typeof FailureCategorySchema>;
 /**
  * Available phases (aligned with run-log-schema.ts)
  */
 export declare const MetricPhaseSchema: z.ZodEnum<{
-    qa: "qa";
-    loop: "loop";
+    exec: "exec";
     spec: "spec";
     "security-review": "security-review";
-    exec: "exec";
     testgen: "testgen";
     test: "test";
+    qa: "qa";
+    loop: "loop";
 }>;
 export type MetricPhase = z.infer<typeof MetricPhaseSchema>;
 /**
@@ -85,13 +86,13 @@ export declare const MetricRunSchema: z.ZodObject<{
     date: z.ZodString;
     issues: z.ZodArray<z.ZodNumber>;
     phases: z.ZodArray<z.ZodEnum<{
-        qa: "qa";
-        loop: "loop";
+        exec: "exec";
         spec: "spec";
         "security-review": "security-review";
-        exec: "exec";
         testgen: "testgen";
         test: "test";
+        qa: "qa";
+        loop: "loop";
     }>>;
     outcome: z.ZodEnum<{
         success: "success";
@@ -110,7 +111,17 @@ export declare const MetricRunSchema: z.ZodObject<{
         build_error: "build_error";
         rate_limit: "rate_limit";
         billing: "billing";
+        pr_creation: "pr_creation";
     }>>;
+    phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        phase: z.ZodString;
+        base: z.ZodString;
+        escalated: z.ZodString;
+    }, z.core.$strip>>>;
     metrics: z.ZodObject<{
         tokensUsed: z.ZodNumber;
         filesChanged: z.ZodNumber;
@@ -135,13 +146,13 @@ export declare const MetricsSchema: z.ZodObject<{
         date: z.ZodString;
         issues: z.ZodArray<z.ZodNumber>;
         phases: z.ZodArray<z.ZodEnum<{
-            qa: "qa";
-            loop: "loop";
+            exec: "exec";
             spec: "spec";
             "security-review": "security-review";
-            exec: "exec";
             testgen: "testgen";
             test: "test";
+            qa: "qa";
+            loop: "loop";
         }>>;
         outcome: z.ZodEnum<{
             success: "success";
@@ -160,7 +171,17 @@ export declare const MetricsSchema: z.ZodObject<{
             build_error: "build_error";
             rate_limit: "rate_limit";
             billing: "billing";
+            pr_creation: "pr_creation";
         }>>;
+        phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            phase: z.ZodString;
+            base: z.ZodString;
+            escalated: z.ZodString;
+        }, z.core.$strip>>>;
         metrics: z.ZodObject<{
             tokensUsed: z.ZodNumber;
             filesChanged: z.ZodNumber;
@@ -193,6 +214,28 @@ export declare function createMetricRun(options: {
     model?: string;
     flags?: string[];
     failureCategory?: FailureCategory;
+    /**
+     * Resolved per-phase model/effort overrides (#914), keyed by phase name.
+     * Pass only the phases that actually had a configured override — a phase
+     * that inherited the CLI default should not appear here at all. See
+     * `resolvePhasePolicies` in `config-resolver.ts`, which already produces
+     * a map shaped this way.
+     */
+    phasePolicies?: Record<string, {
+        model?: string;
+        effort?: string;
+    }>;
+    /**
+     * Effort escalations applied during this run (#915), one entry per
+     * escalated phase execution. Pass only executions that actually escalated
+     * — see `MetricRunSchema.effortEscalations`'s doc comment for why this is
+     * a sibling array rather than an extension of `phasePolicies`.
+     */
+    effortEscalations?: Array<{
+        phase: string;
+        base: string;
+        escalated: string;
+    }>;
     metrics?: Partial<RunMetrics>;
 }): MetricRun;
 /**

package/dist/src/lib/workflow/metrics-schema.js

@@ -96,6 +96,33 @@ export const MetricRunSchema = z.object({
      * existed (additive — no `version` bump required).
      */
     failureCategory: FailureCategorySchema.optional(),
+    /**
+     * Resolved per-phase `model`/`effort` overrides (#914), keyed by phase
+     * name. Only phases with a configured override get an entry — a phase
+     * that inherited the CLI default is omitted entirely, not recorded with
+     * undefined fields. Enum/alias strings only, consistent with this
+     * schema's no-file-paths/no-content privacy contract. Optional and
+     * additive — absent on records written before this field existed.
+     */
+    phasePolicies: z
+        .record(z.string(), z.object({ model: z.string().optional(), effort: z.string().optional() }))
+        .optional(),
+    /**
+     * Effort escalations applied during this run (#915), one entry per
+     * escalated phase execution — distinct from `phasePolicies`, which is a
+     * flat phase→policy map recorded once per run and can't express a value
+     * that changes per retry. Only populated when at least one execution
+     * escalated; omitted entirely (not an empty array) otherwise, matching
+     * `phasePolicies`'s omit-when-empty convention. Phase names and enum
+     * effort strings only, consistent with this schema's privacy contract.
+     */
+    effortEscalations: z
+        .array(z.object({
+        phase: z.string(),
+        base: z.string(),
+        escalated: z.string(),
+    }))
+        .optional(),
     /** Aggregate metrics */
     metrics: RunMetricsSchema,
 });
@@ -137,6 +164,12 @@ export function createMetricRun(options) {
         model: options.model ?? "unknown",
         flags: options.flags ?? [],
         failureCategory: options.failureCategory,
+        ...(options.phasePolicies && Object.keys(options.phasePolicies).length > 0
+            ? { phasePolicies: options.phasePolicies }
+            : {}),
+        ...(options.effortEscalations && options.effortEscalations.length > 0
+            ? { effortEscalations: options.effortEscalations }
+            : {}),
         metrics: {
             tokensUsed: options.metrics?.tokensUsed ?? 0,
             filesChanged: options.metrics?.filesChanged ?? 0,

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

@@ -70,6 +70,17 @@ export declare class MetricsWriter {
         model?: string;
         flags?: string[];
         failureCategory?: FailureCategory;
+        /** Resolved per-phase model/effort overrides (#914). See `createMetricRun`. */
+        phasePolicies?: Record<string, {
+            model?: string;
+            effort?: string;
+        }>;
+        /** Effort escalations applied during this run (#915). See `createMetricRun`. */
+        effortEscalations?: Array<{
+            phase: string;
+            base: string;
+            escalated: string;
+        }>;
         metrics?: Partial<RunMetrics>;
     }): Promise<MetricRun>;
     /**

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

@@ -11,6 +11,18 @@
  * ```
  */
 import { type Phase, type PhaseMarker } from "./state-schema.js";
+/**
+ * Strip markdown code blocks and inline code from text.
+ * This prevents phase markers inside code examples from being parsed.
+ *
+ * Exported for reuse by `spec-recommendation.ts` (#921), which applies the
+ * same code-fence stripping to the `SEQUANT_SPEC` marker so documentation
+ * examples embedding that marker can't false-positive either.
+ *
+ * @param text - The text to strip code from
+ * @returns Text with code blocks and inline code removed
+ */
+export declare function stripMarkdownCode(text: string): string;
 /**
  * Format a phase marker as an HTML comment string for embedding in GitHub comments.
  *

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

@@ -25,10 +25,14 @@ const INLINE_CODE_REGEX = /`[^`\n]+`/g;
  * Strip markdown code blocks and inline code from text.
  * This prevents phase markers inside code examples from being parsed.
  *
+ * Exported for reuse by `spec-recommendation.ts` (#921), which applies the
+ * same code-fence stripping to the `SEQUANT_SPEC` marker so documentation
+ * examples embedding that marker can't false-positive either.
+ *
  * @param text - The text to strip code from
  * @returns Text with code blocks and inline code removed
  */
-function stripMarkdownCode(text) {
+export function stripMarkdownCode(text) {
     // First remove fenced code blocks (multi-line)
     let result = text.replace(FENCED_CODE_BLOCK_REGEX, "");
     // Then remove inline code

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

@@ -11,7 +11,7 @@ import { ShutdownManager } from "../shutdown.js";
 import { Phase, ExecutionConfig, PhaseResult, QaVerdict, PhasePauseHandle } from "./types.js";
 import type { QaSummary } from "./run-log-schema.js";
 import type { AgentPhaseResult, ResumeHandle } from "./drivers/index.js";
-import { SequantError } from "../errors.js";
+import { RateLimitError, SequantError } from "../errors.js";
 /**
  * Leading + trailing throttle. Fires the wrapped callback immediately on the
  * first call, drops subsequent calls that arrive inside `intervalMs` but
@@ -67,7 +67,150 @@ export declare const RATE_LIMIT_RETRY_BACKOFF_MS = 5000;
  * @internal Exported for testing only
  */
 export declare function isWindowExhaustedRateLimit(error: SequantError | undefined, now?: number): boolean;
+/**
+ * Buffer added to a rate-limit reset before waking (#804 AC-5). `resetsAt` is a
+ * floor, not an exact moment: clock skew between this host and the API, plus
+ * server-side rounding, otherwise produce an immediate second rejection on
+ * wake. One minute is negligible against the five-hour/seven-day windows this
+ * exists for.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_BUFFER_MS: number;
+/**
+ * Hard cap on auto-waits per issue (#804 AC-6), independent of the minutes
+ * budget. A window that is still closed on wake must not produce an unbounded
+ * pause loop, so the count bounds the *number* of pauses while
+ * `autoWaitMinutes` bounds their *total duration*. Either bound being spent
+ * halts with today's labeled message.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_MAX_WAITS = 2;
+/**
+ * Granularity of the auto-wait sleep (#804 AC-7). The wait is performed as a
+ * series of ticks rather than one multi-hour `delayFn` call so that (a) the
+ * renderer/heartbeat can be refreshed with the remaining time, and (b) a
+ * Ctrl-C is observed promptly instead of at the wake time.
+ *
+ * @internal Exported for testing only
+ */
+export declare const AUTO_WAIT_TICK_MS: number;
+/**
+ * Mutable per-issue accounting for auto-wait (#804 AC-6).
+ *
+ * Deliberately per-ISSUE, not per-phase: `executePhaseWithRetry` runs once per
+ * phase, so a ledger created inside it would grant every phase its own full
+ * budget and bound. `runIssueWithLogging` creates one and threads it through
+ * all of an issue's phases.
+ */
+export interface AutoWaitLedger {
+    /** Total wait budget in ms. `0` disables auto-wait entirely. */
+    budgetMs: number;
+    /** Number of waits already granted for this issue. */
+    waits: number;
+    /** Cumulative ms already spent waiting for this issue. */
+    spentMs: number;
+}
+/**
+ * Build a fresh ledger from a minutes budget. A missing, negative or
+ * non-finite budget yields a disabled ledger (`budgetMs: 0`) — the default,
+ * which preserves pre-#804 behavior exactly.
+ */
+export declare function createAutoWaitLedger(budgetMinutes?: number): AutoWaitLedger;
+/**
+ * A granted auto-wait: how long to sleep, when to wake, and the narrowed
+ * rate-limit error that justified it (carried so callers need no cast).
+ */
+export interface AutoWaitDecision {
+    /** Ms to sleep. Always > 0. */
+    waitMs: number;
+    /** Epoch ms to wake at — `resetsAt` normalized to ms, plus the buffer. */
+    wakeAtMs: number;
+    /** The rate limit that triggered the wait. Never a `BillingError`. */
+    error: RateLimitError;
+}
+/**
+ * Decide whether to wait out an exhausted rate-limit window (#804 AC-3).
+ *
+ * Deliberately separate from {@link isWindowExhaustedRateLimit} and
+ * {@link RATE_LIMIT_WINDOW_SKIP_THRESHOLD_MS}, which answer *"is this transient
+ * or exhausted?"*. This answers a different question — *"am I willing to wait
+ * that long?"* — and fires ONLY once the former is already true. Keeping them
+ * apart is what leaves `autoWaitMinutes` the single user-facing dial for the
+ * wait-vs-halt outcome.
+ *
+ * Returns `null` (no wait — halt as before) when:
+ * - auto-wait is off, or the per-issue wait count is spent;
+ * - the failure is not a window-exhausted `RateLimitError`. A `BillingError`
+ *   lands here: it is a sibling class, not a subclass, so the `instanceof`
+ *   check inside `isWindowExhaustedRateLimit` excludes it. That is load-bearing
+ *   — a `BillingError` may still carry `resetsAt` (an explicit
+ *   `credits_required`, or a window that has already passed — see the #860
+ *   narrowing in `isBillingFailure`), so gating on the timestamp's presence
+ *   instead of the error type would wait out a credits failure that no amount
+ *   of waiting can heal (AC-4). Since #860, a *live* recognized window
+ *   (`five_hour`/`seven_day*` + future reset) classifies as `RateLimitError`
+ *   upstream even when `out_of_credits` is present, which is what lets the
+ *   real captured subscription payloads reach this decision at all;
+ * - the reset has already passed (nothing to wait for);
+ * - the required wait exceeds the budget REMAINING, not the total (AC-6).
+ *
+ * @internal Exported for testing only
+ */
+export declare function shouldAutoWaitForReset(error: SequantError | undefined, ledger: AutoWaitLedger, now?: number): AutoWaitDecision | null;
+/**
+ * Sleep until an auto-wait's wake time, in ticks (#804 AC-7).
+ *
+ * Chunking the sleep is what makes a multi-hour pause survivable:
+ * - `onTick` refreshes the live display so the wait is visible rather than a
+ *   silent stall (the #574 complaint at 60x scale);
+ * - each tick races the injected `delayFn` against the abort signal, so Ctrl-C
+ *   returns immediately instead of blocking until the wake.
+ *
+ * Reuses the caller's `delayFn` so the wait stays fully test-injectable.
+ *
+ * Returns the ms actually slept and whether the wait was aborted.
+ *
+ * @internal Exported for testing only
+ */
+export declare function waitForWindowReset(waitMs: number, options: {
+    delayFn: (ms: number) => Promise<void>;
+    signal?: AbortSignal;
+    onTick?: (remainingMs: number) => void;
+    now?: () => number;
+    tickMs?: number;
+}): Promise<{
+    sleptMs: number;
+    aborted: boolean;
+}>;
+/**
+ * Run one granted auto-wait end to end (#804): emit the live notices, sleep,
+ * update the ledger, and report whether Ctrl-C interrupted it.
+ *
+ * Shared by both arms of the retry ladder (the cold-start loop and the
+ * `skipColdStartRetry` single-attempt path) so the two cannot drift on
+ * bookkeeping or messaging.
+ *
+ * @internal Exported for testing only
+ */
+export declare function performAutoWait(issueNumber: number, phase: Phase, config: ExecutionConfig, decision: AutoWaitDecision, ledger: AutoWaitLedger, delayFn: (ms: number) => Promise<void>, shutdownManager?: ShutdownManager, spinner?: PhasePauseHandle): Promise<{
+    aborted: boolean;
+}>;
 export declare function parseQaVerdict(output: string): QaVerdict | null;
+/**
+ * Distinguish a QA turn that produced *no verdict at all* from one whose output
+ * was present but unparseable (#853). Returns true when the output is empty /
+ * whitespace, or when its tail contains deferral language — the agent treating
+ * its one-shot phase as if a later turn were available.
+ *
+ * Both cases are hard failures either way; this only refines which message is
+ * emitted, so a false positive is harmless (it swaps one failing message for
+ * another). Kept deliberately conservative and literal to stay ReDoS-safe.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function endedWithoutVerdict(output: string | undefined): boolean;
 /**
  * Parse condensed QA summary from QA phase output (#434).
  *
@@ -109,22 +252,59 @@ export declare function formatDuration(seconds: number): string;
  */
 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 the resolved
- * base ref (see {@link resolveBaseRef}) OR uncommitted work is present.
+ * Three-way classification of what the exec phase left in the worktree (#879).
  *
- * 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.
+ * - `commits`: HEAD has commits unique to it relative to the base ref — real,
+ *   deliverable work that can rebase, push, and become a PR.
+ * - `uncommitted`: no such commits, but the tree is dirty. This is NOT a
+ *   deliverable: uncommitted work cannot rebase, push, or become a PR (#879's
+ *   defect — a dirty tree used to be counted as exec success, producing a run
+ *   that "passed" with no commits and no PR). `paths` names the dirty files.
+ * - `none`: no commits and a clean tree — exec produced literally nothing
+ *   (#534's original empty-branch class).
+ * - `unknown`: a git command failed. Callers fail OPEN on this (treat as work)
+ *   — a transient git error is better diagnosed as a real run than as a
+ *   spurious phase failure on every exec.
+ */
+export type ExecChangeState = {
+    kind: "commits";
+} | {
+    kind: "uncommitted";
+    paths: string[];
+} | {
+    kind: "none";
+} | {
+    kind: "unknown";
+};
+/**
+ * Classify what the exec phase produced in the worktree (#879).
+ *
+ * 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 exec 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`).
+ * 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.
+ * Read-only: runs only `git rev-list` and `git status --porcelain`, so it never
+ * mutates the worktree — an exec phase that fails on an `uncommitted` result
+ * leaves the dirty files exactly where the agent left them (#879 AC-3).
+ *
+ * @internal Exported for testing only.
+ */
+export declare function classifyExecChanges(cwd: string): ExecChangeState;
+/**
+ * Check whether the exec phase produced deliverable work in the worktree.
+ *
+ * Thin boolean wrapper over {@link classifyExecChanges}: only `commits` (real
+ * work) and `unknown` (git error — fail open) count as "has changes". Note the
+ * #879 behaviour change: an `uncommitted`-only tree now returns **false**, since
+ * uncommitted work is not a deliverable. Both callers (the exec guard in
+ * {@link mapAgentSuccessToPhaseResult} and the ready gate) want this stricter
+ * semantics.
  *
  * @internal Exported for testing only.
  */
@@ -195,7 +375,16 @@ export declare function executePhaseWithRetry(issueNumber: number, phase: Phase,
 /** @internal Injected for testing — defaults to module-level executePhase */
 executePhaseFn?: typeof executePhase, 
 /** @internal Injected for testing — defaults to setTimeout-based delay */
-delayFn?: (ms: number) => Promise<void>): Promise<PhaseResult & {
+delayFn?: (ms: number) => Promise<void>, 
+/**
+ * Per-issue auto-wait accounting (#804). Deliberately the LAST parameter:
+ * the #761/#799 regression tests call this function positionally with
+ * `executePhaseFn` at 8 and `delayFn` at 9, and AC-2 requires those tests to
+ * pass unmodified. Defaults to a fresh disabled-or-config-derived ledger, so
+ * a caller that does not thread one still gets correct (bounded) behavior —
+ * just scoped to this phase rather than the issue.
+ */
+autoWaitLedger?: AutoWaitLedger): Promise<PhaseResult & {
     sessionId?: string;
     resumeHandle?: ResumeHandle;
 }>;