sequant 2.9.0 → 2.11.0

package/dist/src/lib/workflow/spec-recommendation.js

@@ -0,0 +1,142 @@
+/**
+ * Structured resolution of the spec→run phase recommendation (#921).
+ *
+ * `parseRecommendedWorkflow` (phase-mapper.ts) regexes the spec agent's
+ * *ephemeral chat text* for a `## Recommended Workflow` section. When the
+ * spec agent posts its plan via a body file instead of restating it in
+ * chat, that regex has nothing to match and the run silently falls back to
+ * label-based phase detection — dropping any recommended phase the label
+ * fallback can never produce (e.g. `testgen`). See #814.
+ *
+ * This module resolves the recommendation through an ordered chain, each
+ * step falling through loudly to the next on failure:
+ *
+ *   1. `marker`         — the durable `<!-- SEQUANT_SPEC: {json} --> `
+ *                          comment marker (this issue's fix)
+ *   2. `comment-prose`  — the same regex as `chat`, applied to the spec
+ *                          plan's GitHub comment body instead of chat text
+ *   3. `chat`           — `parseRecommendedWorkflow` over the agent's
+ *                          captured chat output (existing behavior)
+ *   4. `label-fallback` — `detectPhasesFromLabels` (existing behavior)
+ *
+ * The durable comment marker is the system's existing idiom — see
+ * `SEQUANT_PHASE` in `phase-detection.ts` and the `/assess` HTML markers in
+ * `assess-comment-parser.ts`.
+ */
+import chalk from "chalk";
+import { z } from "zod";
+import { phaseRegistry } from "./phase-registry.js";
+import { GitHubProvider } from "./platforms/github.js";
+import { stripMarkdownCode } from "./phase-detection.js";
+import { parseRecommendedWorkflow, detectPhasesFromLabels, } from "./phase-mapper.js";
+/** Regex to extract the SEQUANT_SPEC marker JSON from an HTML comment. */
+const SPEC_MARKER_REGEX = /<!-- SEQUANT_SPEC: (\{[^}]+\}) -->/g;
+/**
+ * Structural shape of the marker JSON, before phase names are checked
+ * against the phase registry. `qualityLoop` defaults to `false` when
+ * omitted, matching `parseRecommendedWorkflow`'s prose-parsing default.
+ */
+const SpecMarkerJsonSchema = z.object({
+    phases: z.array(z.string()).min(1),
+    qualityLoop: z.boolean().optional().default(false),
+});
+/**
+ * Extract and validate the latest `SEQUANT_SPEC` marker across a set of
+ * comment bodies (oldest-to-newest order, matching `gh`'s natural order).
+ *
+ * Returns `null` when no marker is present at all. Returns `null` and logs a
+ * visible warning when the latest marker is malformed JSON, fails schema
+ * validation, or names a phase the registry doesn't recognize — per AC-2,
+ * an invalid marker falls through to the next resolution step rather than
+ * silently dropping the recommendation or silently ignoring the bad phase.
+ *
+ * Only the *latest* marker is considered (last comment, last match within
+ * it) — a re-spec's marker supersedes an earlier one, matching how a human
+ * reader would interpret the thread.
+ */
+export function parseSpecMarker(commentBodies) {
+    let latestRaw = null;
+    for (const body of commentBodies) {
+        const stripped = stripMarkdownCode(body);
+        SPEC_MARKER_REGEX.lastIndex = 0;
+        let match;
+        while ((match = SPEC_MARKER_REGEX.exec(stripped)) !== null) {
+            latestRaw = match[1];
+        }
+    }
+    if (latestRaw === null) {
+        return null;
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(latestRaw);
+    }
+    catch {
+        console.log(chalk.yellow(`    ⚠ SEQUANT_SPEC marker is not valid JSON — falling through to comment prose`));
+        return null;
+    }
+    const result = SpecMarkerJsonSchema.safeParse(parsedJson);
+    if (!result.success) {
+        console.log(chalk.yellow(`    ⚠ SEQUANT_SPEC marker failed schema validation — falling through to comment prose`));
+        return null;
+    }
+    const unknownPhases = result.data.phases.filter((name) => !phaseRegistry.has(name));
+    if (unknownPhases.length > 0) {
+        console.log(chalk.yellow(`    ⚠ SEQUANT_SPEC marker names unknown phase(s): ${unknownPhases.join(", ")} — falling through to comment prose`));
+        return null;
+    }
+    return { phases: result.data.phases, qualityLoop: result.data.qualityLoop };
+}
+/**
+ * Find the most recently posted comment containing a `## Recommended
+ * Workflow` section and parse it with the existing prose regex.
+ *
+ * Scans newest-to-oldest so a later spec re-run's comment takes precedence
+ * over an earlier one — same intuition as the marker step.
+ */
+function parseCommentProse(commentBodies) {
+    for (let i = commentBodies.length - 1; i >= 0; i--) {
+        const parsed = parseRecommendedWorkflow(commentBodies[i]);
+        if (parsed) {
+            return parsed;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the spec→run phase recommendation through the ordered chain:
+ * comment-marker → comment-prose → chat-text → label-fallback.
+ */
+export function resolveSpecRecommendation(input) {
+    const github = input.githubProvider ?? new GitHubProvider();
+    const commentBodies = github.fetchIssueCommentBodiesSync(String(input.issueNumber));
+    let phases;
+    let qualityLoop;
+    let source;
+    const marker = parseSpecMarker(commentBodies);
+    const prose = marker ? null : parseCommentProse(commentBodies);
+    const chat = marker || prose || !input.chatOutput
+        ? null
+        : parseRecommendedWorkflow(input.chatOutput);
+    if (marker) {
+        ({ phases, qualityLoop } = marker);
+        source = "marker";
+    }
+    else if (prose) {
+        ({ phases, qualityLoop } = prose);
+        source = "comment-prose";
+    }
+    else if (chat) {
+        ({ phases, qualityLoop } = chat);
+        source = "chat";
+    }
+    else {
+        const fallback = detectPhasesFromLabels(input.labels);
+        phases = fallback.phases;
+        qualityLoop = fallback.qualityLoop;
+        source = "label-fallback";
+    }
+    // Spec already ran by the time this resolves — never re-include it,
+    // regardless of which step in the chain produced the result.
+    return { phases: phases.filter((p) => p !== "spec"), qualityLoop, source };
+}

package/dist/src/lib/workflow/state-cleanup.js

@@ -221,13 +221,20 @@ export async function reconcileStateAtStartup(options = {}) {
         const state = await manager.getState();
         const advanced = [];
         const stillPending = [];
-        // Find issues in ready_for_merge, in_progress, or waiting_for_qa_gate state.
+        // Find issues whose PR may have merged since their status was written.
         // in_progress covers PRs merged outside this session (#592).
         // waiting_for_qa_gate covers PRs merged before the next QA-gate run (#606).
+        // waiting_for_human_merge covers #817's `--ready-gate` terminal: a gated
+        // issue never reaches ready_for_merge, so without it a gated issue whose PR
+        // a human then merged stayed here forever and never advanced to merged
+        // (#837). Note this list is deliberately WIDER than `isCompletedIssueStatus`
+        // — it asks "might this have a merged PR?", not "is this done?", which is
+        // why in_progress belongs here but not there.
         for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
             if (issueState.status !== "ready_for_merge" &&
                 issueState.status !== "in_progress" &&
-                issueState.status !== "waiting_for_qa_gate") {
+                issueState.status !== "waiting_for_qa_gate" &&
+                issueState.status !== "waiting_for_human_merge") {
                 continue;
             }
             const issueNum = parseInt(issueNumStr, 10);

package/dist/src/lib/workflow/state-manager.d.ts

@@ -126,6 +126,39 @@ export declare class StateManager {
      * Update PR information for an issue
      */
     updatePRInfo(issueNumber: number, pr: PRInfo): Promise<void>;
+    /**
+     * Record or clear an in-progress auto-wait (#860). `wakeAtMs` sets the
+     * pause marker (and which phase is paused); `null` clears it on wake.
+     *
+     * Unlike the sibling updaters this NEVER throws on an untracked issue —
+     * it is called from a liveness hook during a live wait, and a bookkeeping
+     * miss must not interrupt the pause it is describing.
+     */
+    updateAutoWait(issueNumber: number, phase: string, wakeAtMs: number | null): Promise<void>;
+    /**
+     * Record a durable waitable-window halt (#892 AC-1). Preserves an existing
+     * re-entry counter so repeated halts on a still-closed window keep counting
+     * toward the re-entry bound instead of resetting it.
+     *
+     * Like `updateAutoWait`, NEVER throws on an untracked issue — it runs on a
+     * halt path where bookkeeping must not mask the real failure.
+     */
+    updateWindowHalt(issueNumber: number, phase: string, resumeAtMs: number): Promise<void>;
+    /**
+     * Clear a stale window-halt record (#892) — on any phase success (the
+     * window demonstrably reopened; progress also resets the re-entry counter)
+     * or a non-window failure (the halt cause is no longer waitable, so an
+     * unattended re-entry must not fire on it). No-ops (no state write) when
+     * nothing is recorded; never throws on an untracked issue.
+     */
+    clearWindowHalt(issueNumber: number): Promise<void>;
+    /**
+     * Consume one re-entry attempt for a halted issue (#892 AC-3). Returns the
+     * new count, or `null` when the issue has no window-halt record (nothing to
+     * resume). Called by `sequant resume` immediately before re-entry so a
+     * re-entry that halts again (window still closed) is already counted.
+     */
+    incrementWindowHaltReentries(issueNumber: number): Promise<number | null>;
     /**
      * Update worktree information for an issue
      */

package/dist/src/lib/workflow/state-manager.js

@@ -364,6 +364,89 @@ export class StateManager {
             console.log(`State: PR #${pr.number} linked to issue #${issueNumber}`);
         }
     }
+    /**
+     * Record or clear an in-progress auto-wait (#860). `wakeAtMs` sets the
+     * pause marker (and which phase is paused); `null` clears it on wake.
+     *
+     * Unlike the sibling updaters this NEVER throws on an untracked issue —
+     * it is called from a liveness hook during a live wait, and a bookkeeping
+     * miss must not interrupt the pause it is describing.
+     */
+    async updateAutoWait(issueNumber, phase, wakeAtMs) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState)
+                return;
+            issueState.autoWait =
+                wakeAtMs === null
+                    ? undefined
+                    : { wakeAt: new Date(wakeAtMs).toISOString(), phase };
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
+    /**
+     * Record a durable waitable-window halt (#892 AC-1). Preserves an existing
+     * re-entry counter so repeated halts on a still-closed window keep counting
+     * toward the re-entry bound instead of resetting it.
+     *
+     * Like `updateAutoWait`, NEVER throws on an untracked issue — it runs on a
+     * halt path where bookkeeping must not mask the real failure.
+     */
+    async updateWindowHalt(issueNumber, phase, resumeAtMs) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState)
+                return;
+            issueState.windowHalt = {
+                resumeAt: new Date(resumeAtMs).toISOString(),
+                phase,
+                reentries: issueState.windowHalt?.reentries ?? 0,
+            };
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
+    /**
+     * Clear a stale window-halt record (#892) — on any phase success (the
+     * window demonstrably reopened; progress also resets the re-entry counter)
+     * or a non-window failure (the halt cause is no longer waitable, so an
+     * unattended re-entry must not fire on it). No-ops (no state write) when
+     * nothing is recorded; never throws on an untracked issue.
+     */
+    async clearWindowHalt(issueNumber) {
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState?.windowHalt)
+                return;
+            issueState.windowHalt = undefined;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+    }
+    /**
+     * Consume one re-entry attempt for a halted issue (#892 AC-3). Returns the
+     * new count, or `null` when the issue has no window-halt record (nothing to
+     * resume). Called by `sequant resume` immediately before re-entry so a
+     * re-entry that halts again (window still closed) is already counted.
+     */
+    async incrementWindowHaltReentries(issueNumber) {
+        let newCount = null;
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState?.windowHalt)
+                return;
+            issueState.windowHalt.reentries += 1;
+            newCount = issueState.windowHalt.reentries;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
+        return newCount;
+    }
     /**
      * Update worktree information for an issue
      */

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

@@ -213,6 +213,14 @@ export declare const RelayStateSchema: z.ZodObject<{
     messageCount: z.ZodNumber;
 }, z.core.$strip>;
 export type RelayState = z.infer<typeof RelayStateSchema>;
+/**
+ * Maximum scheduler re-entries per window-halted issue (#892 AC-3). Mirrors
+ * `AUTO_WAIT_MAX_WAITS` (#804): both bound how often sequant returns to the
+ * same closed rate-limit window before declaring the halt terminal. Lives
+ * here — beside the `windowHalt.reentries` field it bounds — so display
+ * surfaces (`sequant status`) can import it without pulling in the run path.
+ */
+export declare const MAX_RESUME_REENTRIES = 2;
 /**
  * Complete state for a single issue
  */
@@ -342,6 +350,15 @@ export declare const IssueStateSchema: z.ZodObject<{
         token: z.ZodString;
         originCwd: z.ZodString;
     }, z.core.$strip>>;
+    autoWait: z.ZodOptional<z.ZodObject<{
+        wakeAt: z.ZodString;
+        phase: z.ZodString;
+    }, z.core.$strip>>;
+    windowHalt: z.ZodOptional<z.ZodObject<{
+        resumeAt: z.ZodString;
+        phase: z.ZodString;
+        reentries: z.ZodNumber;
+    }, z.core.$strip>>;
     resolvedAt: z.ZodOptional<z.ZodString>;
     lastActivity: z.ZodString;
     createdAt: z.ZodString;
@@ -482,6 +499,15 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             token: z.ZodString;
             originCwd: z.ZodString;
         }, z.core.$strip>>;
+        autoWait: z.ZodOptional<z.ZodObject<{
+            wakeAt: z.ZodString;
+            phase: z.ZodString;
+        }, z.core.$strip>>;
+        windowHalt: z.ZodOptional<z.ZodObject<{
+            resumeAt: z.ZodString;
+            phase: z.ZodString;
+            reentries: z.ZodNumber;
+        }, z.core.$strip>>;
         resolvedAt: z.ZodOptional<z.ZodString>;
         lastActivity: z.ZodString;
         createdAt: z.ZodString;

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

@@ -197,6 +197,14 @@ export const RelayStateSchema = z.object({
     startedAt: z.string().datetime(),
     messageCount: z.number().int().nonnegative(),
 });
+/**
+ * Maximum scheduler re-entries per window-halted issue (#892 AC-3). Mirrors
+ * `AUTO_WAIT_MAX_WAITS` (#804): both bound how often sequant returns to the
+ * same closed rate-limit window before declaring the halt terminal. Lives
+ * here — beside the `windowHalt.reentries` field it bounds — so display
+ * surfaces (`sequant status`) can import it without pulling in the run path.
+ */
+export const MAX_RESUME_REENTRIES = 2;
 /**
  * Complete state for a single issue
  */
@@ -248,6 +256,45 @@ export const IssueStateSchema = z.object({
         originCwd: z.string(),
     })
         .optional(),
+    /**
+     * An in-progress auto-wait (#860): the phase is deliberately paused until a
+     * rate-limit window reopens at `wakeAt`. Written at wait start and cleared
+     * on wake, so `sequant status` can say "waiting until 07:01" instead of
+     * showing an hours-stale in-progress phase indistinguishable from a hang
+     * (#856). The write itself also refreshes `state.json`'s mtime — the
+     * activity proxy several liveness surfaces poll.
+     */
+    autoWait: z
+        .object({
+        /** ISO timestamp of the scheduled wake (resetsAt + buffer). */
+        wakeAt: z.string().datetime(),
+        /** Phase that is paused. */
+        phase: z.string(),
+    })
+        .optional(),
+    /**
+     * A durable halt on an exhausted rate-limit window (#892): the run exited
+     * cleanly (lock released) and can be re-entered by `sequant resume` once
+     * the window reopens at `resumeAt`. Unlike `autoWait` (a live in-process
+     * pause), this record survives reboots — it is the machine-readable
+     * contract between the halt and an unattended scheduler re-entry.
+     * Written at a waitable-window halt, cleared on any phase success or a
+     * non-window failure (the halt cause is then no longer waitable).
+     */
+    windowHalt: z
+        .object({
+        /** ISO timestamp after which re-entry can proceed (resetsAt + buffer). */
+        resumeAt: z.string().datetime(),
+        /** Phase that halted. */
+        phase: z.string(),
+        /**
+         * Re-entry attempts consumed (#892 AC-3). Incremented by `sequant
+         * resume` before each re-entry; a window that never reopens is bounded
+         * by MAX_RESUME_REENTRIES instead of ping-ponging a scheduler.
+         */
+        reentries: z.number().int().min(0),
+    })
+        .optional(),
     /** When the issue transitioned to a terminal status (merged/abandoned/closed) */
     resolvedAt: z.string().datetime().optional(),
     /** Most recent activity timestamp */