sequant 1.20.2 → 2.0.0

package/dist/src/lib/workflow/run-reflect.js

@@ -103,7 +103,7 @@ function suggestImprovements(input, observations, suggestions) {
         const allSame = phaseSets.every((s) => s === phaseSets[0]);
         if (allSame) {
             observations.push("All issues ran identical phases despite different requirements");
-            suggestions.push("Use `/solve` first to get per-issue phase recommendations");
+            suggestions.push("Use `/assess` first to get per-issue phase recommendations");
         }
     }
     // Check if quality loop was triggered

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

@@ -17,6 +17,7 @@
  */
 import { spawnSync } from "child_process";
 import { StateManager } from "./state-manager.js";
+import { isTerminalStatus } from "./state-schema.js";
 import { checkPRMergeStatus, isIssueMergedIntoMain } from "./pr-status.js";
 /**
  * Get list of active worktree paths
@@ -109,6 +110,9 @@ export async function cleanupStaleEntries(options = {}) {
                         // Mark as abandoned (kept for review)
                         orphaned.push(issueNum);
                         issueState.status = "abandoned";
+                        if (!issueState.resolvedAt) {
+                            issueState.resolvedAt = new Date().toISOString();
+                        }
                         if (options.verbose) {
                             console.log(`   → Marked as abandoned (kept for review)`);
                         }
@@ -144,6 +148,20 @@ export async function cleanupStaleEntries(options = {}) {
                         delete state.issues[issueNumStr];
                     }
                 }
+                continue;
+            }
+            // Force-clean: remove ALL resolved entries regardless of worktree/TTL
+            if (isTerminalStatus(issueState.status)) {
+                if (options.verbose) {
+                    console.log(`🧹 Resolved: #${issueNum} (${issueState.status})`);
+                }
+                if (issueState.status === "merged") {
+                    merged.push(issueNum);
+                }
+                removed.push(issueNum);
+                if (!options.dryRun) {
+                    delete state.issues[issueNumStr];
+                }
             }
         }
         // Save updated state
@@ -223,6 +241,9 @@ export async function reconcileStateAtStartup(options = {}) {
                 // Advance state to merged
                 issueState.status = "merged";
                 issueState.lastActivity = new Date().toISOString();
+                if (!issueState.resolvedAt) {
+                    issueState.resolvedAt = new Date().toISOString();
+                }
                 advanced.push(issueNum);
             }
             else {

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

@@ -27,6 +27,8 @@ export interface StateManagerOptions {
     statePath?: string;
     /** Enable verbose logging */
     verbose?: boolean;
+    /** Lock acquisition timeout in ms (default: 5000) */
+    lockTimeout?: number;
 }
 /**
  * Manages persistent workflow state
@@ -35,20 +37,42 @@ export declare class StateManager {
     private statePath;
     private verbose;
     private cachedState;
+    private lockTimeout;
     constructor(options?: StateManagerOptions);
+    /**
+     * Execute a callback while holding an exclusive file lock.
+     *
+     * Ensures that concurrent processes serialize their read-modify-write
+     * cycles on state.json. The cache is cleared before executing the
+     * callback so the latest on-disk state is read.
+     *
+     * External callers (e.g., reconcileState) should use this to wrap
+     * any read-modify-write cycle that includes getState() + saveState().
+     */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+    private acquireLock;
+    private releaseLock;
     /**
      * Get the full path to the state file
      */
     getStatePath(): string;
     /**
-     * Read the current workflow state
+     * Read the current workflow state.
+     *
+     * **Warning:** This method does NOT acquire a lock. For concurrent access
+     * (e.g., reconcileState), wrap your read-modify-write cycle in withLock()
+     * to prevent interleaving with other state mutations.
      *
      * Returns empty state if file doesn't exist.
      * Throws on parse errors.
      */
     getState(): Promise<WorkflowState>;
     /**
-     * Write state to disk using atomic write
+     * Write state to disk using atomic write.
+     *
+     * **Warning:** This method does NOT acquire a lock. For concurrent access
+     * (e.g., reconcileState), wrap your read-modify-write cycle in withLock()
+     * to prevent interleaving with other state mutations.
      *
      * Writes to a temp file first, then renames to prevent corruption
      * if the process is interrupted during write.
@@ -63,9 +87,16 @@ export declare class StateManager {
      */
     getIssueState(issueNumber: number): Promise<IssueState | null>;
     /**
-     * Get all issue states
+     * Get all issue states, filtering out expired resolved issues based on TTL.
+     *
+     * Uses `run.resolvedIssueTTL` from settings (default: 7 days).
+     * Expired entries are hidden in-memory; disk cleanup happens lazily on next write.
      */
     getAllIssueStates(): Promise<Record<number, IssueState>>;
+    /**
+     * Get all issue states without TTL filtering (for --all escape hatch).
+     */
+    getAllIssueStatesUnfiltered(): Promise<Record<number, IssueState>>;
     /**
      * Get the current phase for an issue
      */

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

@@ -23,7 +23,8 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { WorkflowStateSchema, STATE_FILE_PATH, createEmptyState, createIssueState, createPhaseState, updateAcceptanceCriteriaSummary, } from "./state-schema.js";
+import { WorkflowStateSchema, STATE_FILE_PATH, createEmptyState, createIssueState, createPhaseState, updateAcceptanceCriteriaSummary, isTerminalStatus, isExpired, } from "./state-schema.js";
+import { getSettings } from "../settings.js";
 /**
  * Manages persistent workflow state
  */
@@ -31,9 +32,88 @@ export class StateManager {
     statePath;
     verbose;
     cachedState = null;
+    lockTimeout;
     constructor(options = {}) {
         this.statePath = options.statePath ?? STATE_FILE_PATH;
         this.verbose = options.verbose ?? false;
+        this.lockTimeout = options.lockTimeout ?? 5000;
+    }
+    /**
+     * Execute a callback while holding an exclusive file lock.
+     *
+     * Ensures that concurrent processes serialize their read-modify-write
+     * cycles on state.json. The cache is cleared before executing the
+     * callback so the latest on-disk state is read.
+     *
+     * External callers (e.g., reconcileState) should use this to wrap
+     * any read-modify-write cycle that includes getState() + saveState().
+     */
+    async withLock(fn) {
+        const lockPath = this.statePath + ".lock";
+        await this.acquireLock(lockPath);
+        try {
+            // Clear cache so we read the latest on-disk state
+            this.clearCache();
+            return await fn();
+        }
+        finally {
+            this.releaseLock(lockPath);
+        }
+    }
+    async acquireLock(lockPath) {
+        const start = Date.now();
+        const retryDelay = 50; // ms
+        // Ensure directory exists for lock file
+        const dir = path.dirname(lockPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        while (true) {
+            try {
+                // O_EXCL: fail atomically if file already exists
+                const fd = fs.openSync(lockPath, "wx");
+                fs.writeSync(fd, String(process.pid));
+                fs.closeSync(fd);
+                return; // Lock acquired
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "EEXIST")
+                    throw err;
+                // Check for stale lock (older than timeout)
+                try {
+                    const stat = fs.statSync(lockPath);
+                    const age = Date.now() - stat.mtimeMs;
+                    if (age > this.lockTimeout) {
+                        // Stale lock — remove and retry
+                        try {
+                            fs.unlinkSync(lockPath);
+                        }
+                        catch {
+                            // Another process may have removed it
+                        }
+                        continue;
+                    }
+                }
+                catch {
+                    // Lock file disappeared between open and stat — retry
+                    continue;
+                }
+                if (Date.now() - start > this.lockTimeout) {
+                    throw new Error(`Timeout acquiring state lock after ${this.lockTimeout}ms`);
+                }
+                // Wait and retry
+                await new Promise((resolve) => setTimeout(resolve, retryDelay));
+            }
+        }
+    }
+    releaseLock(lockPath) {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            // Ignore — lock may have been cleaned up by stale detection
+        }
     }
     /**
      * Get the full path to the state file
@@ -42,7 +122,11 @@ export class StateManager {
         return this.statePath;
     }
     /**
-     * Read the current workflow state
+     * Read the current workflow state.
+     *
+     * **Warning:** This method does NOT acquire a lock. For concurrent access
+     * (e.g., reconcileState), wrap your read-modify-write cycle in withLock()
+     * to prevent interleaving with other state mutations.
      *
      * Returns empty state if file doesn't exist.
      * Throws on parse errors.
@@ -72,7 +156,11 @@ export class StateManager {
         }
     }
     /**
-     * Write state to disk using atomic write
+     * Write state to disk using atomic write.
+     *
+     * **Warning:** This method does NOT acquire a lock. For concurrent access
+     * (e.g., reconcileState), wrap your read-modify-write cycle in withLock()
+     * to prevent interleaving with other state mutations.
      *
      * Writes to a temp file first, then renames to prevent corruption
      * if the process is interrupted during write.
@@ -82,6 +170,24 @@ export class StateManager {
         WorkflowStateSchema.parse(state);
         // Update lastUpdated timestamp
         state.lastUpdated = new Date().toISOString();
+        // Lazy disk cleanup: prune expired entries before writing
+        try {
+            const settings = await getSettings();
+            const ttlDays = settings.run.resolvedIssueTTL ?? 7;
+            const pruned = [];
+            for (const [key, entry] of Object.entries(state.issues)) {
+                if (isExpired(entry, ttlDays)) {
+                    pruned.push(key);
+                    delete state.issues[key];
+                }
+            }
+            if (pruned.length > 0 && this.verbose) {
+                console.log(`📊 Pruned ${pruned.length} expired issue(s): ${pruned.map((k) => `#${k}`).join(", ")}`);
+            }
+        }
+        catch {
+            // Settings read failure should not block state writes
+        }
         // Ensure directory exists
         const dir = path.dirname(this.statePath);
         if (!fs.existsSync(dir)) {
@@ -119,9 +225,27 @@ export class StateManager {
         return state.issues[String(issueNumber)] ?? null;
     }
     /**
-     * Get all issue states
+     * Get all issue states, filtering out expired resolved issues based on TTL.
+     *
+     * Uses `run.resolvedIssueTTL` from settings (default: 7 days).
+     * Expired entries are hidden in-memory; disk cleanup happens lazily on next write.
      */
     async getAllIssueStates() {
+        const state = await this.getState();
+        const settings = await getSettings();
+        const ttlDays = settings.run.resolvedIssueTTL ?? 7;
+        const result = {};
+        for (const [key, value] of Object.entries(state.issues)) {
+            if (!isExpired(value, ttlDays)) {
+                result[parseInt(key, 10)] = value;
+            }
+        }
+        return result;
+    }
+    /**
+     * Get all issue states without TTL filtering (for --all escape hatch).
+     */
+    async getAllIssueStatesUnfiltered() {
         const state = await this.getState();
         const result = {};
         for (const [key, value] of Object.entries(state.issues)) {
@@ -140,11 +264,13 @@ export class StateManager {
      * Initialize tracking for a new issue
      */
     async initializeIssue(issueNumber, title, options) {
-        const state = await this.getState();
-        // Create new issue state
-        const issueState = createIssueState(issueNumber, title, options);
-        state.issues[String(issueNumber)] = issueState;
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            // Create new issue state
+            const issueState = createIssueState(issueNumber, title, options);
+            state.issues[String(issueNumber)] = issueState;
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 Initialized issue #${issueNumber}: ${title}`);
         }
@@ -153,35 +279,39 @@ export class StateManager {
      * Update the status of a specific phase
      */
     async updatePhaseStatus(issueNumber, phase, status, options) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        // Update phase state
-        const phaseState = createPhaseState(status);
-        if (status === "completed" || status === "failed" || status === "skipped") {
-            phaseState.completedAt = new Date().toISOString();
-        }
-        if (options?.error) {
-            phaseState.error = options.error;
-        }
-        if (options?.iteration !== undefined) {
-            phaseState.iteration = options.iteration;
-        }
-        // Preserve startedAt if already set
-        const existingPhase = issueState.phases[phase];
-        if (existingPhase?.startedAt && status !== "pending") {
-            phaseState.startedAt = existingPhase.startedAt;
-        }
-        issueState.phases[phase] = phaseState;
-        issueState.currentPhase = phase;
-        issueState.lastActivity = new Date().toISOString();
-        // Update issue status based on phase status
-        if (status === "in_progress" && issueState.status === "not_started") {
-            issueState.status = "in_progress";
-        }
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            // Update phase state
+            const phaseState = createPhaseState(status);
+            if (status === "completed" ||
+                status === "failed" ||
+                status === "skipped") {
+                phaseState.completedAt = new Date().toISOString();
+            }
+            if (options?.error) {
+                phaseState.error = options.error;
+            }
+            if (options?.iteration !== undefined) {
+                phaseState.iteration = options.iteration;
+            }
+            // Preserve startedAt if already set
+            const existingPhase = issueState.phases[phase];
+            if (existingPhase?.startedAt && status !== "pending") {
+                phaseState.startedAt = existingPhase.startedAt;
+            }
+            issueState.phases[phase] = phaseState;
+            issueState.currentPhase = phase;
+            issueState.lastActivity = new Date().toISOString();
+            // Update issue status based on phase status
+            if (status === "in_progress" && issueState.status === "not_started") {
+                issueState.status = "in_progress";
+            }
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 Phase ${phase} → ${status} for issue #${issueNumber}`);
         }
@@ -190,14 +320,20 @@ export class StateManager {
      * Update the overall issue status
      */
     async updateIssueStatus(issueNumber, status) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        issueState.status = status;
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            issueState.status = status;
+            issueState.lastActivity = new Date().toISOString();
+            // Record resolvedAt on first transition to terminal status
+            if (isTerminalStatus(status) && !issueState.resolvedAt) {
+                issueState.resolvedAt = new Date().toISOString();
+            }
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 Issue #${issueNumber} status → ${status}`);
         }
@@ -206,14 +342,16 @@ export class StateManager {
      * Update PR information for an issue
      */
     async updatePRInfo(issueNumber, pr) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        issueState.pr = pr;
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            issueState.pr = pr;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 PR #${pr.number} linked to issue #${issueNumber}`);
         }
@@ -222,15 +360,17 @@ export class StateManager {
      * Update worktree information for an issue
      */
     async updateWorktreeInfo(issueNumber, worktree, branch) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        issueState.worktree = worktree;
-        issueState.branch = branch;
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            issueState.worktree = worktree;
+            issueState.branch = branch;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 Worktree updated for issue #${issueNumber}: ${worktree}`);
         }
@@ -239,29 +379,33 @@ export class StateManager {
      * Update session ID for an issue (for resume)
      */
     async updateSessionId(issueNumber, sessionId) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        issueState.sessionId = sessionId;
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            issueState.sessionId = sessionId;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
     }
     /**
      * Update loop iteration for an issue
      */
     async updateLoopIteration(issueNumber, iteration) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        if (issueState.loop) {
-            issueState.loop.iteration = iteration;
-        }
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            if (issueState.loop) {
+                issueState.loop.iteration = iteration;
+            }
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 Loop iteration ${iteration} for issue #${issueNumber}`);
         }
@@ -270,12 +414,14 @@ export class StateManager {
      * Remove an issue from state
      */
     async removeIssue(issueNumber) {
-        const state = await this.getState();
-        if (!state.issues[String(issueNumber)]) {
-            return; // Already removed
-        }
-        delete state.issues[String(issueNumber)];
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            if (!state.issues[String(issueNumber)]) {
+                return; // Already removed
+            }
+            delete state.issues[String(issueNumber)];
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 Removed issue #${issueNumber} from state`);
         }
@@ -287,14 +433,16 @@ export class StateManager {
      * Used by /spec to store extracted ACs from the issue body.
      */
     async updateAcceptanceCriteria(issueNumber, acceptanceCriteria) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        issueState.acceptanceCriteria = acceptanceCriteria;
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            issueState.acceptanceCriteria = acceptanceCriteria;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 AC updated for issue #${issueNumber}: ${acceptanceCriteria.items.length} items`);
         }
@@ -313,29 +461,31 @@ export class StateManager {
      * Automatically recalculates the summary counts.
      */
     async updateACStatus(issueNumber, acId, status, notes) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        if (!issueState.acceptanceCriteria) {
-            throw new Error(`Issue #${issueNumber} has no acceptance criteria`);
-        }
-        // Find and update the AC item
-        const acItem = issueState.acceptanceCriteria.items.find((item) => item.id === acId);
-        if (!acItem) {
-            throw new Error(`AC "${acId}" not found in issue #${issueNumber}. ` +
-                `Available IDs: ${issueState.acceptanceCriteria.items.map((i) => i.id).join(", ")}`);
-        }
-        acItem.status = status;
-        acItem.verifiedAt = new Date().toISOString();
-        if (notes !== undefined) {
-            acItem.notes = notes;
-        }
-        // Recalculate summary counts
-        issueState.acceptanceCriteria = updateAcceptanceCriteriaSummary(issueState.acceptanceCriteria);
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            if (!issueState.acceptanceCriteria) {
+                throw new Error(`Issue #${issueNumber} has no acceptance criteria`);
+            }
+            // Find and update the AC item
+            const acItem = issueState.acceptanceCriteria.items.find((item) => item.id === acId);
+            if (!acItem) {
+                throw new Error(`AC "${acId}" not found in issue #${issueNumber}. ` +
+                    `Available IDs: ${issueState.acceptanceCriteria.items.map((i) => i.id).join(", ")}`);
+            }
+            acItem.status = status;
+            acItem.verifiedAt = new Date().toISOString();
+            if (notes !== undefined) {
+                acItem.notes = notes;
+            }
+            // Recalculate summary counts
+            issueState.acceptanceCriteria = updateAcceptanceCriteriaSummary(issueState.acceptanceCriteria);
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 AC ${acId} → ${status} for issue #${issueNumber}`);
         }
@@ -347,14 +497,16 @@ export class StateManager {
      * Used by /spec to store the scope assessment result.
      */
     async updateScopeAssessment(issueNumber, scopeAssessment) {
-        const state = await this.getState();
-        const issueState = state.issues[String(issueNumber)];
-        if (!issueState) {
-            throw new Error(`Issue #${issueNumber} not found in state`);
-        }
-        issueState.scopeAssessment = scopeAssessment;
-        issueState.lastActivity = new Date().toISOString();
-        await this.saveState(state);
+        await this.withLock(async () => {
+            const state = await this.getState();
+            const issueState = state.issues[String(issueNumber)];
+            if (!issueState) {
+                throw new Error(`Issue #${issueNumber} not found in state`);
+            }
+            issueState.scopeAssessment = scopeAssessment;
+            issueState.lastActivity = new Date().toISOString();
+            await this.saveState(state);
+        });
         if (this.verbose) {
             console.log(`📊 Scope assessment updated for issue #${issueNumber}: ${scopeAssessment.verdict}`);
         }