sequant 2.1.2 → 2.3.0

package/dist/src/lib/assess-comment-parser.d.ts

@@ -75,7 +75,12 @@ export interface AssessMarkers {
  */
 export type SolveMarkers = AssessMarkers;
 /**
- * Check if a comment is an assess command output (new format)
+ * Check if a comment is an assess command output (new format).
+ *
+ * Matches either prose markers (e.g., "## Assess Analysis") or the durable
+ * HTML action marker `<!-- assess:action=... -->` written by every /assess
+ * comment regardless of prose format. The HTML marker is the contract;
+ * prose can change.
  */
 export declare function isAssessComment(body: string): boolean;
 /**
@@ -87,6 +92,14 @@ export declare function isSolveComment(body: string): boolean;
  * Find the most recent assess/solve comment from a list of comments
  */
 export declare function findAssessComment(comments: IssueComment[]): IssueComment | null;
+/**
+ * Find every assess/solve comment in chronological order (oldest first).
+ *
+ * Preserves the input order of `comments`, which is the order GitHub returns
+ * them (chronological). Callers that need the most recent comment should
+ * read the last element.
+ */
+export declare function findAllAssessComments(comments: IssueComment[]): IssueComment[];
 /**
  * Find the most recent solve comment from a list of comments
  * @deprecated Use findAssessComment instead
@@ -135,3 +148,48 @@ export declare function assessCoversIssue(workflow: AssessWorkflowResult, issueN
  * @deprecated Use assessCoversIssue instead
  */
 export declare function solveCoversIssue(workflow: AssessWorkflowResult, issueNumber: number): boolean;
+/**
+ * Build a one-line supersession header for a new assess comment.
+ *
+ * Format:
+ * - 0 priors → null (caller omits the header entirely)
+ * - 1 prior  → `Supersedes prior assess from <date> (<action>)`
+ * - ≥2 priors → `Supersedes N prior assessments (most recent: <date>)`
+ *
+ * Priors must be passed in chronological order (oldest first), matching
+ * the output of findAllAssessComments.
+ */
+export declare function buildSupersessionHeader(priors: IssueComment[]): string | null;
+/**
+ * Result of churn detection: whether to fire the warning, the count
+ * of prior assessments, and the date of the first one.
+ */
+export interface ChurnResult {
+    isChurn: boolean;
+    count: number;
+    firstDate?: string;
+}
+/**
+ * Detect re-assessment churn — repeated /assess invocations without
+ * an intervening exec phase. Fires only when ≥3 priors exist and no
+ * exec phase marker appears in any comment dated after the first prior.
+ *
+ * `allComments` should be the full comment list from the issue
+ * (including the prior assess comments themselves) so we can search
+ * for SEQUANT_PHASE exec markers in non-assess comments.
+ */
+export declare function detectChurn(priors: IssueComment[], allComments: IssueComment[]): ChurnResult;
+/**
+ * Decide whether to prompt the user before posting a new assess comment
+ * that conflicts with the most recent prior recommendation.
+ *
+ * Prompts only when:
+ *   - A prior action exists, AND
+ *   - The prior action is PROCEED or REWRITE (the "do work" actions
+ *     where flipping to PARK/CLOSE/etc. needs explicit confirmation), AND
+ *   - The new action differs from the prior.
+ *
+ * Skips the prompt for prior CLOSE/PARK/CLARIFY/MERGE — flipping
+ * away from those is rarely "wrong" and the prompt would just be noise.
+ */
+export declare function shouldPromptOnConflict(priorAction: AssessAction | undefined, newAction: AssessAction | undefined): boolean;

package/dist/src/lib/assess-comment-parser.js

@@ -70,6 +70,11 @@ const HTML_MARKER_PATTERN = /<!--\s*(?:assess|solve):(\w[\w-]*)=([\w,.-]*)\s*-->
  * Pattern to extract assess-specific HTML markers (takes precedence)
  */
 const ASSESS_HTML_MARKER_PATTERN = /<!--\s*assess:(\w[\w-]*)=([\w,.-]*)\s*-->/g;
+/**
+ * Non-global pattern for `.test()` checks. Matches any assess/solve action
+ * marker — the durable contract written by /assess regardless of prose format.
+ */
+const ASSESS_ACTION_MARKER_PATTERN = /<!--\s*(?:assess|solve):action=[\w-]+\s*-->/;
 /**
  * Pattern to extract issue numbers from header
  * Matches: "## Solve Workflow for Issues: 123, 456" or "#123"
@@ -88,10 +93,17 @@ const VALID_ACTIONS = [
 ];
 // ─── Detection Functions ────────────────────────────────────────────────────
 /**
- * Check if a comment is an assess command output (new format)
+ * Check if a comment is an assess command output (new format).
+ *
+ * Matches either prose markers (e.g., "## Assess Analysis") or the durable
+ * HTML action marker `<!-- assess:action=... -->` written by every /assess
+ * comment regardless of prose format. The HTML marker is the contract;
+ * prose can change.
  */
 export function isAssessComment(body) {
-    return ALL_MARKERS.some((marker) => body.includes(marker));
+    if (ALL_MARKERS.some((marker) => body.includes(marker)))
+        return true;
+    return ASSESS_ACTION_MARKER_PATTERN.test(body);
 }
 /**
  * Check if a comment is a solve command output (legacy format)
@@ -111,6 +123,16 @@ export function findAssessComment(comments) {
     }
     return null;
 }
+/**
+ * Find every assess/solve comment in chronological order (oldest first).
+ *
+ * Preserves the input order of `comments`, which is the order GitHub returns
+ * them (chronological). Callers that need the most recent comment should
+ * read the last element.
+ */
+export function findAllAssessComments(comments) {
+    return comments.filter((c) => isAssessComment(c.body));
+}
 /**
  * Find the most recent solve comment from a list of comments
  * @deprecated Use findAssessComment instead
@@ -342,3 +364,103 @@ export function assessCoversIssue(workflow, issueNumber) {
 export function solveCoversIssue(workflow, issueNumber) {
     return assessCoversIssue(workflow, issueNumber);
 }
+// ─── Prior-Assessment Detection ─────────────────────────────────────────────
+/**
+ * Pattern matching exec phase markers in any comment.
+ * Used by detectChurn to differentiate "no execution" churn from
+ * legitimate re-assessment after exec.
+ */
+const EXEC_PHASE_MARKER_PATTERN = /<!--\s*SEQUANT_PHASE:\s*\{[^}]*"phase"\s*:\s*"exec"[^}]*\}\s*-->/;
+/**
+ * Format a comment's createdAt timestamp as YYYY-MM-DD.
+ * Falls back to the raw value when missing or unparseable so output
+ * still says something useful.
+ */
+function formatAssessDate(createdAt) {
+    if (!createdAt)
+        return "unknown date";
+    const parsed = new Date(createdAt);
+    if (isNaN(parsed.getTime()))
+        return createdAt;
+    return parsed.toISOString().slice(0, 10);
+}
+/**
+ * Build a one-line supersession header for a new assess comment.
+ *
+ * Format:
+ * - 0 priors → null (caller omits the header entirely)
+ * - 1 prior  → `Supersedes prior assess from <date> (<action>)`
+ * - ≥2 priors → `Supersedes N prior assessments (most recent: <date>)`
+ *
+ * Priors must be passed in chronological order (oldest first), matching
+ * the output of findAllAssessComments.
+ */
+export function buildSupersessionHeader(priors) {
+    if (priors.length === 0)
+        return null;
+    const mostRecent = priors[priors.length - 1];
+    const date = formatAssessDate(mostRecent.createdAt);
+    if (priors.length === 1) {
+        const workflow = parseAssessWorkflow(mostRecent.body);
+        const action = workflow.action ?? "unknown";
+        return `Supersedes prior assess from ${date} (${action})`;
+    }
+    return `Supersedes ${priors.length} prior assessments (most recent: ${date})`;
+}
+/**
+ * Detect re-assessment churn — repeated /assess invocations without
+ * an intervening exec phase. Fires only when ≥3 priors exist and no
+ * exec phase marker appears in any comment dated after the first prior.
+ *
+ * `allComments` should be the full comment list from the issue
+ * (including the prior assess comments themselves) so we can search
+ * for SEQUANT_PHASE exec markers in non-assess comments.
+ */
+export function detectChurn(priors, allComments) {
+    const count = priors.length;
+    if (count < 3) {
+        return { isChurn: false, count };
+    }
+    const firstPrior = priors[0];
+    const firstDate = formatAssessDate(firstPrior.createdAt);
+    const firstTimestamp = firstPrior.createdAt
+        ? new Date(firstPrior.createdAt).getTime()
+        : NaN;
+    const hasExecAfterFirst = allComments.some((c) => {
+        if (!EXEC_PHASE_MARKER_PATTERN.test(c.body))
+            return false;
+        if (!Number.isFinite(firstTimestamp))
+            return true;
+        if (!c.createdAt)
+            return true;
+        const ts = new Date(c.createdAt).getTime();
+        if (isNaN(ts))
+            return true;
+        return ts >= firstTimestamp;
+    });
+    return {
+        isChurn: !hasExecAfterFirst,
+        count,
+        firstDate,
+    };
+}
+/**
+ * Decide whether to prompt the user before posting a new assess comment
+ * that conflicts with the most recent prior recommendation.
+ *
+ * Prompts only when:
+ *   - A prior action exists, AND
+ *   - The prior action is PROCEED or REWRITE (the "do work" actions
+ *     where flipping to PARK/CLOSE/etc. needs explicit confirmation), AND
+ *   - The new action differs from the prior.
+ *
+ * Skips the prompt for prior CLOSE/PARK/CLARIFY/MERGE — flipping
+ * away from those is rarely "wrong" and the prompt would just be noise.
+ */
+export function shouldPromptOnConflict(priorAction, newAction) {
+    if (!priorAction || !newAction)
+        return false;
+    if (priorAction === newAction)
+        return false;
+    return priorAction === "PROCEED" || priorAction === "REWRITE";
+}

package/dist/src/lib/cli-ui/format.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared formatting helpers used by run-renderer and friends.
+ *
+ * Lives in cli-ui/ so renderer and heartbeat can share without depending on
+ * the legacy phase-spinner module.
+ */
+/**
+ * Format elapsed time in human-readable form.
+ *
+ * @example
+ *   formatElapsedTime(5)       // "5s"
+ *   formatElapsedTime(75)      // "1m 15s"
+ *   formatElapsedTime(3725)    // "1h 2m"
+ */
+export declare function formatElapsedTime(seconds: number): string;
+/**
+ * Format a wall-clock timestamp as `HH:MM:SS`. Used by the non-TTY renderer.
+ */
+export declare function formatTimestamp(date: Date): string;

package/dist/src/lib/cli-ui/format.js

@@ -0,0 +1,34 @@
+/**
+ * Shared formatting helpers used by run-renderer and friends.
+ *
+ * Lives in cli-ui/ so renderer and heartbeat can share without depending on
+ * the legacy phase-spinner module.
+ */
+/**
+ * Format elapsed time in human-readable form.
+ *
+ * @example
+ *   formatElapsedTime(5)       // "5s"
+ *   formatElapsedTime(75)      // "1m 15s"
+ *   formatElapsedTime(3725)    // "1h 2m"
+ */
+export function formatElapsedTime(seconds) {
+    const s = Math.max(0, Math.floor(seconds));
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600) {
+        const m = Math.floor(s / 60);
+        const r = s % 60;
+        return r > 0 ? `${m}m ${r}s` : `${m}m`;
+    }
+    const h = Math.floor(s / 3600);
+    const r = Math.floor((s % 3600) / 60);
+    return r > 0 ? `${h}h ${r}m` : `${h}h`;
+}
+/**
+ * Format a wall-clock timestamp as `HH:MM:SS`. Used by the non-TTY renderer.
+ */
+export function formatTimestamp(date) {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}

package/dist/src/lib/cli-ui/run-renderer-types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Types shared between RunRenderer modes (TTY, non-TTY, orchestrator).
+ *
+ * The renderer is event-driven: a `ProgressEvent` flows in and the renderer
+ * decides whether to update the live zone, append an event line, or both.
+ */
+export type ProgressEventKind = "start" | "complete" | "failed";
+/** Raw event from batch-executor `emitProgressLine` / `onProgress` callbacks. */
+export interface ProgressEvent {
+    issue: number;
+    phase: string;
+    event: ProgressEventKind;
+    durationSeconds?: number;
+    error?: string;
+    /**
+     * Quality-loop iteration (1-based). Set on the `loop` phase event and on
+     * retried phase events (exec, qa, ...) once the outer loop iterates past 1.
+     * Surfaced in the events log as `(attempt N/M)` and in the live-zone status
+     * cell as `loop N/M` (#624 Item 3).
+     */
+    iteration?: number;
+}
+/** Per-phase status tracked inside the renderer state machine. */
+export interface PhaseState {
+    name: string;
+    status: "pending" | "running" | "done" | "failed";
+    startedAt?: number;
+    durationMs?: number;
+    /** Loop iteration label (e.g. "loop 2/3"). */
+    loopIteration?: number;
+    /**
+     * #624 Item 4: normalized signature of the most recent failure for THIS
+     * phase (ANSI-stripped, lowercased, first 80 chars, trimmed). Per-phase so
+     * "same failure as attempt N" never references a different phase's attempt.
+     */
+    lastFailureSignature?: string;
+    /**
+     * #624 Item 4: 1-based attempt number for this phase when
+     * `lastFailureSignature` was first observed. Referenced in the abbreviated
+     * form `(attempt N/M, same failure as attempt K)`.
+     */
+    firstAttemptForSignature?: number;
+}
+/** Per-issue status tracked inside the renderer state machine. */
+export interface IssueState {
+    issueNumber: number;
+    title?: string;
+    worktreePath?: string;
+    branch?: string;
+    status: "queued" | "running" | "done" | "failed";
+    phases: PhaseState[];
+    currentPhase?: string;
+    startedAt?: number;
+    completedAt?: number;
+    prNumber?: number;
+    prUrl?: string;
+    /** Optional sub-status line (e.g. "claude streaming · editing src/cli.ts"). */
+    subStatus?: string;
+    /** Last QA verdict / error reason for failed issues. */
+    failureReason?: string;
+    /**
+     * AC-23: auto-detect mode — render `Phase: detecting…` until spec finishes
+     * and the resolved plan is known.
+     */
+    autoDetect?: boolean;
+}
+/** Initial registration payload — fed at runner start so queued rows render. */
+export interface IssueRegistration {
+    issueNumber: number;
+    title?: string;
+    worktreePath?: string;
+    branch?: string;
+    /**
+     * AC-23: when true, the issue runs in auto-detect mode. The renderer shows
+     * `Phase: detecting…` while spec is running (before the resolved phase plan
+     * is known) and switches to the normal phase header once spec completes.
+     */
+    autoDetect?: boolean;
+}
+/** Per-issue summary fields used by the final summary table. */
+export interface IssueSummary {
+    issueNumber: number;
+    success: boolean;
+    durationSeconds?: number;
+    phases: Array<{
+        name: string;
+        success: boolean;
+    }>;
+    loopTriggered?: boolean;
+    prNumber?: number;
+    prUrl?: string;
+    failureReason?: string;
+    qaVerdict?: string;
+    unmetCount?: number;
+}
+/** Inputs needed to render the final summary block. */
+export interface SummaryRenderInput {
+    issues: IssueSummary[];
+    totalDurationSeconds?: number;
+    logPath?: string | null;
+    dryRun?: boolean;
+}
+/** Public renderer interface — all modes implement this. */
+export interface RunRenderer {
+    /** Register an issue so it shows as `queued` before the first phase event. */
+    registerIssue(reg: IssueRegistration): void;
+    /** Feed a progress event from batch-executor. */
+    onEvent(event: ProgressEvent): void;
+    /** Mark an issue as completed with PR info. Called by orchestrator. */
+    setPullRequest(issue: number, prNumber: number, prUrl: string): void;
+    /** Pause live updates so verbose streaming can write through. */
+    pause(): void;
+    /** Resume live updates after streaming ends. */
+    resume(): void;
+    /** Render the final summary block. */
+    renderSummary(input: SummaryRenderInput): void;
+    /** Tear down timers, cursor state, signal listeners. */
+    dispose(): void;
+}
+/**
+ * Options shared by every renderer mode. Most are optional; defaults match
+ * production behaviour (real stdout, real timers, real signals).
+ */
+export interface RenderOptions {
+    /** Override stdout writer. Defaults to `process.stdout.write`. */
+    stdoutWrite?: (s: string) => void;
+    /** Override stderr writer. Defaults to `process.stderr.write`. */
+    stderrWrite?: (s: string) => void;
+    /** Override clock. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Override "wall clock" used for non-TTY timestamps. Defaults to `() => new Date()`. */
+    wallClock?: () => Date;
+    /** Override TTY detection. Defaults to `process.stdout.isTTY`. */
+    isTTY?: boolean;
+    /** Override terminal column count. Defaults to `process.stdout.columns`. */
+    columns?: number;
+    /** Disable color output (NO_COLOR). */
+    noColor?: boolean;
+    /** Heartbeat tick interval for the live zone (ms). Defaults to 1000. */
+    liveTickMs?: number;
+    /** Idle heartbeat interval for non-TTY mode (ms). Defaults to 60_000. */
+    nonTtyHeartbeatMs?: number;
+    /** Don't subscribe to SIGWINCH (used in tests). */
+    noSignalListeners?: boolean;
+    /**
+     * AC-26: when a running phase has been active for longer than this many ms
+     * with no completion event, the status header flips to `⚠ stalled · …`.
+     * Defaults to half the phase timeout when wired from settings; effectively
+     * disabled (10× the default heartbeat) when omitted.
+     */
+    stallThresholdMs?: number;
+    /**
+     * AC-28: cap visible per-issue rows in the multi-issue live grid. When the
+     * total issue count exceeds this, the oldest done rows roll up into a
+     * single `✔ {N} done` summary row at the top. Defaults to 10.
+     */
+    multiIssueRowCap?: number;
+    /**
+     * #624 Item 1: terminal row count. The TTY live zone caps its frame height
+     * at `max(8, rows - 5)` so `log-update` never deals with a frame taller than
+     * the terminal — otherwise it loses cursor tracking and appends fresh frames
+     * instead of replacing them. Defaults to `process.stdout.rows` or 24.
+     */
+    rows?: number;
+    /**
+     * #624 Item 3 / D2: total allowed quality-loop iterations. Used by every
+     * retry-suffix site (`(attempt N/M)` / `loop N/M`) so the M denominator
+     * tracks the configured maximum instead of being hardcoded. Defaults to 3.
+     */
+    maxLoopIterations?: number;
+    /**
+     * When true, `renderSummary` is rendered even if no issues were registered.
+     * Default: false (matches existing displaySummary behaviour).
+     */
+    alwaysRenderSummary?: boolean;
+}
+/**
+ * Mode the renderer should run in. Auto-detected by `createRunRenderer` from
+ * env + TTY, but explicit selection is supported for tests.
+ */
+export type RendererMode = "tty" | "non-tty" | "orchestrator";

package/dist/src/lib/cli-ui/run-renderer-types.js

@@ -0,0 +1,7 @@
+/**
+ * Types shared between RunRenderer modes (TTY, non-TTY, orchestrator).
+ *
+ * The renderer is event-driven: a `ProgressEvent` flows in and the renderer
+ * decides whether to update the live zone, append an event line, or both.
+ */
+export {};