sequant 2.9.0 → 2.11.0

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -48,6 +48,37 @@ export declare const QaVerdictSchema: z.ZodEnum<{
     NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
 }>;
 export type QaVerdict = z.infer<typeof QaVerdictSchema>;
+/**
+ * Source that produced the resolved spec→run phase recommendation (#921).
+ *
+ * Ordered by resolution priority: a durable structured marker in the spec's
+ * GitHub comment beats the same comment's prose section, which beats the
+ * spec agent's ephemeral chat text, which beats label-based guessing.
+ */
+export declare const SpecRecommendationSourceSchema: z.ZodEnum<{
+    marker: "marker";
+    "comment-prose": "comment-prose";
+    chat: "chat";
+    "label-fallback": "label-fallback";
+}>;
+export type SpecRecommendationSource = z.infer<typeof SpecRecommendationSourceSchema>;
+/**
+ * Resolved spec→run phase recommendation, recorded on the issue log so
+ * fallback frequency is auditable (#921 AC-4). Additive/optional — absent on
+ * runs that never reached spec resolution (e.g. spec failed) or predate this
+ * field, keeping the persisted-log schema stable at `version: 1`.
+ */
+export declare const SpecRecommendationSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        marker: "marker";
+        "comment-prose": "comment-prose";
+        chat: "chat";
+        "label-fallback": "label-fallback";
+    }>;
+    phases: z.ZodArray<z.ZodString>;
+    qualityLoop: z.ZodBoolean;
+}, z.core.$strip>;
+export type SpecRecommendation = z.infer<typeof SpecRecommendationSchema>;
 /**
  * File diff statistics for a single file (AC-3)
  */
@@ -91,6 +122,7 @@ export declare const ErrorContextSchema: z.ZodObject<{
         build_error: "build_error";
         rate_limit: "rate_limit";
         billing: "billing";
+        pr_creation: "pr_creation";
     }>;
     errorType: z.ZodOptional<z.ZodString>;
     errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -174,6 +206,7 @@ export declare const PhaseLogSchema: z.ZodObject<{
             build_error: "build_error";
             rate_limit: "rate_limit";
             billing: "billing";
+            pr_creation: "pr_creation";
         }>;
         errorType: z.ZodOptional<z.ZodString>;
         errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -253,6 +286,7 @@ export declare const IssueLogSchema: z.ZodObject<{
                 build_error: "build_error";
                 rate_limit: "rate_limit";
                 billing: "billing";
+                pr_creation: "pr_creation";
             }>;
             errorType: z.ZodOptional<z.ZodString>;
             errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -260,8 +294,20 @@ export declare const IssueLogSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     totalDurationSeconds: z.ZodNumber;
+    aborted: z.ZodOptional<z.ZodBoolean>;
+    abortReason: z.ZodOptional<z.ZodString>;
     prNumber: z.ZodOptional<z.ZodNumber>;
     prUrl: z.ZodOptional<z.ZodString>;
+    specRecommendation: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<{
+            marker: "marker";
+            "comment-prose": "comment-prose";
+            chat: "chat";
+            "label-fallback": "label-fallback";
+        }>;
+        phases: z.ZodArray<z.ZodString>;
+        qualityLoop: z.ZodBoolean;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type IssueLog = z.infer<typeof IssueLogSchema>;
 /**
@@ -284,6 +330,7 @@ export declare const RunSummarySchema: z.ZodObject<{
     passed: z.ZodNumber;
     failed: z.ZodNumber;
     partial: z.ZodDefault<z.ZodNumber>;
+    aborted: z.ZodDefault<z.ZodNumber>;
     totalDurationSeconds: z.ZodNumber;
 }, z.core.$strip>;
 export type RunSummary = z.infer<typeof RunSummarySchema>;
@@ -374,6 +421,7 @@ export declare const RunLogSchema: z.ZodObject<{
                     build_error: "build_error";
                     rate_limit: "rate_limit";
                     billing: "billing";
+                    pr_creation: "pr_creation";
                 }>;
                 errorType: z.ZodOptional<z.ZodString>;
                 errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -381,18 +429,32 @@ export declare const RunLogSchema: z.ZodObject<{
             }, z.core.$strip>>;
         }, z.core.$strip>>;
         totalDurationSeconds: z.ZodNumber;
+        aborted: z.ZodOptional<z.ZodBoolean>;
+        abortReason: z.ZodOptional<z.ZodString>;
         prNumber: z.ZodOptional<z.ZodNumber>;
         prUrl: z.ZodOptional<z.ZodString>;
+        specRecommendation: z.ZodOptional<z.ZodObject<{
+            source: z.ZodEnum<{
+                marker: "marker";
+                "comment-prose": "comment-prose";
+                chat: "chat";
+                "label-fallback": "label-fallback";
+            }>;
+            phases: z.ZodArray<z.ZodString>;
+            qualityLoop: z.ZodBoolean;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     summary: z.ZodObject<{
         totalIssues: z.ZodNumber;
         passed: z.ZodNumber;
         failed: z.ZodNumber;
         partial: z.ZodDefault<z.ZodNumber>;
+        aborted: z.ZodDefault<z.ZodNumber>;
         totalDurationSeconds: z.ZodNumber;
     }, z.core.$strip>;
     startCommit: z.ZodOptional<z.ZodString>;
     endCommit: z.ZodOptional<z.ZodString>;
+    abortedBy: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RunLog = z.infer<typeof RunLogSchema>;
 /**
@@ -421,6 +483,7 @@ export declare function generateLogFilename(runId: string, startTime: Date): str
  */
 export declare function createEmptyRunLog(config: RunConfig, options?: {
     startCommit?: string;
+    startTime?: Date;
 }): Omit<RunLog, "endTime">;
 /**
  * Create a phase log entry
@@ -448,6 +511,7 @@ export declare function completePhaseLog(phaseLog: Omit<PhaseLog, "endTime" | "d
  */
 export declare function finalizeRunLog(runLog: Omit<RunLog, "endTime">, options?: {
     endCommit?: string;
+    abortedBy?: string;
 }): RunLog;
 /**
  * Derive an issue's overall log status from its phase log entries (#766).
@@ -460,5 +524,10 @@ export declare function finalizeRunLog(runLog: Omit<RunLog, "endTime">, options?
  * verdict (mirrors the live-card rule); an unrecovered failure still leaves a
  * non-loop phase failed. Priority among latest attempts: failure > timeout >
  * success.
+ *
+ * An issue with no phase entries is a `failure`, not a `success` (#856). The
+ * only way to reach that state is for `startIssue` to have run while no phase
+ * ever completed — i.e. the run was cut short. Returning `success` there is
+ * what let a SIGTERM'd run persist as a pass with an empty `phases[]`.
  */
 export declare function deriveIssueLogStatus(phases: PhaseLog[]): IssueStatus;

package/dist/src/lib/workflow/run-log-schema.js

@@ -42,6 +42,33 @@ export const QaVerdictSchema = z.enum([
     "AC_NOT_MET",
     "NEEDS_VERIFICATION",
 ]);
+/**
+ * Source that produced the resolved spec→run phase recommendation (#921).
+ *
+ * Ordered by resolution priority: a durable structured marker in the spec's
+ * GitHub comment beats the same comment's prose section, which beats the
+ * spec agent's ephemeral chat text, which beats label-based guessing.
+ */
+export const SpecRecommendationSourceSchema = z.enum([
+    "marker",
+    "comment-prose",
+    "chat",
+    "label-fallback",
+]);
+/**
+ * Resolved spec→run phase recommendation, recorded on the issue log so
+ * fallback frequency is auditable (#921 AC-4). Additive/optional — absent on
+ * runs that never reached spec resolution (e.g. spec failed) or predate this
+ * field, keeping the persisted-log schema stable at `version: 1`.
+ */
+export const SpecRecommendationSchema = z.object({
+    /** Which step in the resolution chain produced this result */
+    source: SpecRecommendationSourceSchema,
+    /** Resolved phases, spec excluded (spec already ran) */
+    phases: z.array(PhaseSchema),
+    /** Whether the quality loop should be enabled */
+    qualityLoop: z.boolean(),
+});
 /**
  * File diff statistics for a single file (AC-3)
  */
@@ -82,7 +109,7 @@ export const ErrorContextSchema = z.object({
     /**
      * Classified error category (legacy, kept for backwards compatibility).
      * Keep in sync with `ERROR_CATEGORIES` in `error-classifier.ts` —
-     * `rate_limit` / `billing` added by #761 AC-6.
+     * `rate_limit` / `billing` added by #761 AC-6, `pr_creation` by #920.
      */
     category: z.enum([
         "context_overflow",
@@ -92,6 +119,7 @@ export const ErrorContextSchema = z.object({
         "timeout",
         "rate_limit",
         "billing",
+        "pr_creation",
         "unknown",
     ]),
     /** Typed error class name (AC-8), e.g. "ApiError", "BuildError" */
@@ -180,10 +208,26 @@ export const IssueLogSchema = z.object({
     phases: z.array(PhaseLogSchema),
     /** Total execution time in seconds */
     totalDurationSeconds: z.number().nonnegative(),
+    /**
+     * Set when this issue never finished because the run was terminated from
+     * outside (#856). Reuses the `"failure"` status — additive boolean rather
+     * than a new `IssueStatus` enum value, matching the `capped` precedent
+     * above, so the persisted-log schema stays stable at `version: 1`.
+     *
+     * Without this, a run killed mid-flight persisted as `success`: `startIssue`
+     * seeds `status: "success"` and only `logPhase` ever revises it, so an issue
+     * whose first phase never completed was written out as a pass with an empty
+     * `phases[]`.
+     */
+    aborted: z.boolean().optional(),
+    /** Human-readable cause of the abort (e.g. `terminated by SIGTERM`). */
+    abortReason: z.string().optional(),
     /** PR number if created after successful QA */
     prNumber: z.number().int().positive().optional(),
     /** PR URL if created after successful QA */
     prUrl: z.string().optional(),
+    /** How the spec→run phase recommendation was resolved (#921 AC-4) */
+    specRecommendation: SpecRecommendationSchema.optional(),
 });
 /**
  * Run configuration
@@ -219,6 +263,14 @@ export const RunSummarySchema = z.object({
      * `.default(0)` keeps logs written before this field parseable.
      */
     partial: z.number().int().nonnegative().default(0),
+    /**
+     * Number of issues cut short by an external signal (#856). A sub-count of
+     * `failed`, not a fourth disjoint bucket — aborted issues carry
+     * `status: "failure"` so existing consumers keep working, and this field
+     * says whether the failure was the run's own or something killing it.
+     * `.default(0)` keeps logs written before this field parseable.
+     */
+    aborted: z.number().int().nonnegative().default(0),
     /** Total execution time in seconds */
     totalDurationSeconds: z.number().nonnegative(),
 });
@@ -246,6 +298,11 @@ export const RunLogSchema = z.object({
     startCommit: z.string().optional(),
     /** Git commit SHA at run end (AC-2) */
     endCommit: z.string().optional(),
+    /**
+     * Signal that terminated the run, when it ended by external signal rather
+     * than by finishing (#856). Present iff at least one issue is `aborted`.
+     */
+    abortedBy: z.string().optional(),
 });
 /**
  * Default log directory paths
@@ -276,7 +333,9 @@ export function generateLogFilename(runId, startTime) {
  */
 export function createEmptyRunLog(config, options) {
     const runId = randomUUID();
-    const startTime = new Date().toISOString();
+    // #867: use the caller-supplied run origin when provided so the log's wall
+    // clock shares the orchestrator's start; fall back to now for standalone use.
+    const startTime = (options?.startTime ?? new Date()).toISOString();
     return {
         version: 1,
         runId,
@@ -288,6 +347,7 @@ export function createEmptyRunLog(config, options) {
             passed: 0,
             failed: 0,
             partial: 0,
+            aborted: 0,
             totalDurationSeconds: 0,
         },
         startCommit: options?.startCommit,
@@ -343,6 +403,11 @@ export function finalizeRunLog(runLog, options) {
     // #766: `partial` gets its own bucket so an all-partial run isn't counted as
     // `0 passed · 0 failed` — it landed in neither before.
     const partial = runLog.issues.filter((i) => i.status === "partial").length;
+    // #856: aborted issues are also counted in `failed` (they carry
+    // `status: "failure"`); this is the sub-count that says *why* they failed,
+    // so a run killed from outside is distinguishable from one whose phases
+    // genuinely failed.
+    const aborted = runLog.issues.filter((i) => i.aborted).length;
     return {
         ...runLog,
         endTime: endTime.toISOString(),
@@ -351,9 +416,13 @@ export function finalizeRunLog(runLog, options) {
             passed,
             failed,
             partial,
+            aborted,
             totalDurationSeconds,
         },
         endCommit: options?.endCommit ?? runLog.endCommit,
+        ...((options?.abortedBy ?? runLog.abortedBy) && {
+            abortedBy: options?.abortedBy ?? runLog.abortedBy,
+        }),
     };
 }
 /**
@@ -367,6 +436,11 @@ export function finalizeRunLog(runLog, options) {
  * verdict (mirrors the live-card rule); an unrecovered failure still leaves a
  * non-loop phase failed. Priority among latest attempts: failure > timeout >
  * success.
+ *
+ * An issue with no phase entries is a `failure`, not a `success` (#856). The
+ * only way to reach that state is for `startIssue` to have run while no phase
+ * ever completed — i.e. the run was cut short. Returning `success` there is
+ * what let a SIGTERM'd run persist as a pass with an empty `phases[]`.
  */
 export function deriveIssueLogStatus(phases) {
     const latest = new Map();
@@ -376,6 +450,8 @@ export function deriveIssueLogStatus(phases) {
         latest.set(p.phase, p.status);
     }
     const statuses = [...latest.values()];
+    if (statuses.length === 0)
+        return "failure";
     if (statuses.some((s) => s === "failure"))
         return "failure";
     if (statuses.some((s) => s === "timeout"))

package/dist/src/lib/workflow/run-orchestrator.d.ts

@@ -164,6 +164,13 @@ export interface RunResult {
     mergedOptions: RunOptions;
     /** Log writer (for reflection access) */
     logWriter: LogWriter | null;
+    /**
+     * Run wall-clock duration in seconds, computed once by the orchestrator from
+     * the run's start and end (#867). The post-run summary reads THIS value rather
+     * than re-summing per-issue durations — under `--parallel` that sum
+     * double-counts overlapping issues and over-reports by ~the concurrency factor.
+     */
+    wallClockDurationSeconds: number;
 }
 /**
  * CLI-free workflow execution engine.
@@ -188,6 +195,18 @@ export declare class RunOrchestrator {
      * listening (#504, AC-3).
      */
     getEmitter(): WorkflowEventEmitter;
+    /**
+     * The wrapped progress sink handed to the batch executor — every phase
+     * lifecycle event enters the orchestrator through here.
+     *
+     * @internal Exported for testing only. `applyProgressEvent` is private and
+     * depends on `issueStates`/`phaseStartTimes`/`emitter`, so there is no way
+     * to exercise its branches short of a full `run()`. Without this seam the
+     * #804 `waiting` branch would be untestable — and an untested `waiting`
+     * branch is not cosmetic: falling through to the complete/failed handler
+     * marks a merely-paused phase `failed` and emits `phase_failed`.
+     */
+    getProgressCallback(): ProgressCallback;
     /**
      * Point-in-time view of the entire run.
      *