specrails-desktop 2.36.0 → 2.42.2

package/server/dist/milestone-chain.js

@@ -0,0 +1,487 @@
+"use strict";
+// Server-durable milestone launch chain (premium-milestone-progress, D3/D4).
+//
+// "Launch Milestone N" in sequential mode: chunk the milestone's todo specs
+// (≤3 per rail), launch chunk 1 through the ORDINARY rails launch route, and
+// — when that chunk's delivery settles — launch the next chunk STACKED on the
+// delivered branch, so a greenfield walking skeleton accumulates without
+// waiting for a merge. The plan lives in SQLite (survives window close, app
+// restart, machine sleep), advances from the delivery-settle chokepoint (the
+// `rail.pr_state` broadcast tapped in the project's bound broadcast — the
+// engine's `onLoopRunFinished` fires BEFORE the delivery row leaves
+// `building`, so it is only a fallback for delivery-less shared-cwd runs),
+// pauses with a typed reason on any failure (never skips ahead), and is
+// visible/controllable (resume / cancel) from every surface.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MilestoneChainManager = exports.MAX_TICKETS_PER_CHAIN_CHUNK = void 0;
+exports.isMilestoneChainEnabled = isMilestoneChainEnabled;
+exports.chunkTickets = chunkTickets;
+exports.chainRailName = chainRailName;
+const milestone_progress_1 = require("./milestone-progress");
+const milestone_chain_store_1 = require("./milestone-chain-store");
+const ids_1 = require("./ids");
+exports.MAX_TICKETS_PER_CHAIN_CHUNK = 3;
+/** `SPECRAILS_MILESTONE_CHAIN=false|0|off` ⇒ every milestone launch is parallel and no row is written. */
+function isMilestoneChainEnabled(env = process.env) {
+    const raw = env.SPECRAILS_MILESTONE_CHAIN;
+    if (raw === undefined || raw === '')
+        return true;
+    const normalized = raw.trim().toLowerCase();
+    return !(normalized === '0' || normalized === 'false' || normalized === 'off');
+}
+function chunkTickets(ticketIds, size = exports.MAX_TICKETS_PER_CHAIN_CHUNK) {
+    const chunks = [];
+    for (let i = 0; i < ticketIds.length; i += size)
+        chunks.push(ticketIds.slice(i, i + size));
+    return chunks;
+}
+function chainRailName(n, chunkIndex, totalChunks) {
+    const label = (0, milestone_progress_1.milestoneLabelFor)(n);
+    return totalChunks === 1 ? label : `${label} · ${chunkIndex + 1}`;
+}
+const SUCCESS_DECISIONS = new Set(['on_review', 'no_changes', 'pr_draft', 'pr_ready', 'completed', 'merged']);
+class MilestoneChainManager {
+    db;
+    projectId;
+    io;
+    constructor(db, projectId, io) {
+        this.db = db;
+        this.projectId = projectId;
+        this.io = io;
+    }
+    now() {
+        return this.io.now?.() ?? Date.now();
+    }
+    enabled() {
+        return this.io.enabled?.() ?? isMilestoneChainEnabled();
+    }
+    /** Non-terminal chains. */
+    listActive() {
+        return (0, milestone_chain_store_1.listActiveChains)(this.db).map(milestone_chain_store_1.toChainSnapshot);
+    }
+    /** Newest chain per milestone, any status (feeds the progress model). */
+    listForProgress() {
+        const seen = new Set();
+        const out = [];
+        for (const row of (0, milestone_chain_store_1.listChains)(this.db)) {
+            if (seen.has(row.milestone_n))
+                continue;
+            seen.add(row.milestone_n);
+            out.push((0, milestone_chain_store_1.toChainSnapshot)(row));
+        }
+        return out;
+    }
+    get(id) {
+        const row = (0, milestone_chain_store_1.getChain)(this.db, id);
+        return row ? (0, milestone_chain_store_1.toChainSnapshot)(row) : null;
+    }
+    emit(row) {
+        try {
+            this.io.broadcast({
+                type: 'milestone.chain_changed',
+                projectId: this.projectId,
+                chain: (0, milestone_chain_store_1.toChainSnapshot)(row),
+                timestamp: new Date(this.now()).toISOString(),
+            });
+        }
+        catch { /* durable row is authoritative */ }
+    }
+    todoTicketIds(n) {
+        const label = (0, milestone_progress_1.milestoneLabelFor)(n);
+        return this.io.readTickets()
+            .filter((t) => t.status === 'todo' && Array.isArray(t.labels) && t.labels.includes(label))
+            .map((t) => t.id)
+            .sort((a, b) => a - b);
+    }
+    /** Create → assign → launch ONE chunk on a fresh rail — or, for a retry,
+     *  on the rail the failed attempt used when nothing undecided sits on it. */
+    async launchChunk(n, chunks, chunkIndex, baseBranch, reuseRailIndex = null, baseDeliveryIds) {
+        const ticketIds = chunks[chunkIndex];
+        let railIndex;
+        const name = chainRailName(n, chunkIndex, chunks.length);
+        const byName = reuseRailIndex === null ? this.freeRailNamed(name) : null;
+        if (reuseRailIndex !== null) {
+            railIndex = reuseRailIndex;
+        }
+        else if (byName !== null) {
+            railIndex = byName;
+        }
+        else {
+            const rail = await this.io.createRail(name);
+            if (!rail.ok)
+                return rail;
+            railIndex = rail.railIndex;
+        }
+        const assigned = await this.io.assignTickets(railIndex, ticketIds);
+        if (!assigned.ok)
+            return assigned;
+        const launched = await this.io.launch(railIndex, { mode: 'batch-implement', ...(baseDeliveryIds?.length ? { baseDeliveryIds } : baseBranch ? { baseBranch } : {}) });
+        if (!launched.ok)
+            return launched;
+        const delivery = this.io.activeDeliveryForRail(railIndex);
+        return {
+            ok: true,
+            entry: { chunk: chunkIndex + 1, railIndex, ticketIds, runIds: launched.loopRunIds, deliveryId: delivery?.id ?? null },
+        };
+    }
+    /** A rail from an earlier chain that already carries this name and holds no
+     *  undecided delivery — reused instead of allocating a duplicate. */
+    freeRailNamed(name) {
+        try {
+            const index = this.io.findRailByName?.(name) ?? null;
+            if (index === null)
+                return null;
+            return this.io.activeDeliveryForRail(index) ? null : index;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The rail a retried chunk can reuse: its previous attempt's rail when no
+     *  undecided delivery still sits there (a failed delivery the user has not
+     *  reviewed keeps the rail — the retry then takes a fresh one). */
+    reusableRailFor(row, chunkIndex) {
+        const previous = (0, milestone_chain_store_1.parseLaunched)(row).find((l) => l.chunk === chunkIndex + 1);
+        if (!previous)
+            return null;
+        try {
+            return this.io.activeDeliveryForRail(previous.railIndex) ? null : previous.railIndex;
+        }
+        catch {
+            return null;
+        }
+    }
+    async start(n, requestedMode, opts = {}) {
+        const enabled = this.enabled();
+        const autoAdvance = opts.autoAdvance !== false;
+        const mode = enabled ? requestedMode : 'parallel';
+        const active = (0, milestone_chain_store_1.listActiveChains)(this.db).find((c) => c.milestone_n === n);
+        if (active)
+            return { ok: false, status: 409, error: 'chain_active', chainId: active.id };
+        const blueprint = this.io.readBlueprint();
+        const milestone = blueprint?.milestones[n - 1];
+        if (!blueprint || !milestone)
+            return { ok: false, status: 404, error: 'milestone_not_found' };
+        const ticketIds = this.todoTicketIds(n);
+        if (ticketIds.length === 0)
+            return { ok: false, status: 400, error: 'no_tickets', detail: `no todo specs labeled ${(0, milestone_progress_1.milestoneLabelFor)(n)}` };
+        const chunks = chunkTickets(ticketIds);
+        if (mode === 'parallel') {
+            const launched = [];
+            let failure = null;
+            for (let i = 0; i < chunks.length; i++) {
+                const r = await this.launchChunk(n, chunks, i, null);
+                if (!r.ok) {
+                    failure = r;
+                    break;
+                }
+                launched.push(r.entry);
+            }
+            if (launched.length === 0 && failure)
+                return { ok: false, status: failure.status, error: failure.error, detail: failure.detail };
+            let chainId = null;
+            if (enabled) {
+                // Recorded `completed` so parallel milestones show chunk ordering in
+                // the same progress model; never advances anything.
+                const row = (0, milestone_chain_store_1.createChain)(this.db, { id: (0, ids_1.newId)(), milestoneN: n, milestoneId: milestone.id, mode, chunks, integrationBranch: await this.safeIntegrationBranch(), status: 'completed', nowMs: this.now() });
+                (0, milestone_chain_store_1.updateChain)(this.db, row.id, 'completed', { nextChunk: launched.length, launched }, this.now());
+                chainId = row.id;
+                const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+                if (fresh)
+                    this.emit(fresh);
+            }
+            return { ok: true, status: 202, chainId, launched, pending: chunks.slice(launched.length) };
+        }
+        const row = (0, milestone_chain_store_1.createChain)(this.db, {
+            id: (0, ids_1.newId)(), milestoneN: n, milestoneId: milestone.id, mode, chunks,
+            integrationBranch: await this.safeIntegrationBranch(), autoAdvance, nowMs: this.now(),
+        });
+        const first = await this.launchChunk(n, chunks, 0, null);
+        if (!first.ok) {
+            // Nothing launched ⇒ no chain remains active (the route relays the guard).
+            (0, milestone_chain_store_1.updateChain)(this.db, row.id, 'running', { status: 'cancelled', pauseReason: `launch_rejected:${first.error}` }, this.now());
+            return { ok: false, status: first.status, error: first.error, detail: first.detail, chainId: row.id };
+        }
+        this.recordLaunched(row.id, first.entry);
+        const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+        if (fresh)
+            this.emit(fresh);
+        return { ok: true, status: 202, chainId: row.id, launched: [first.entry], pending: chunks.slice(1) };
+    }
+    async safeIntegrationBranch() {
+        try {
+            return await this.io.integrationBranch();
+        }
+        catch {
+            return null;
+        }
+    }
+    recordLaunched(chainId, entry) {
+        const row = (0, milestone_chain_store_1.getChain)(this.db, chainId);
+        if (!row)
+            return;
+        // A retry REPLACES the failed attempt's entry for that chunk (the delivery
+        // rows keep the history); a fresh chunk appends.
+        const launched = (0, milestone_chain_store_1.parseLaunched)(row).filter((l) => l.chunk !== entry.chunk);
+        (0, milestone_chain_store_1.updateChain)(this.db, chainId, row.status, {
+            nextChunk: entry.chunk,
+            currentRailIndex: entry.railIndex,
+            currentRunIds: entry.runIds,
+            currentDeliveryId: entry.deliveryId,
+            lastRunOutcome: null,
+            status: 'running',
+            pauseReason: null,
+            retryChunk: null,
+            launched: [...launched, entry],
+        }, this.now());
+    }
+    pause(row, reason, patch = {}) {
+        if ((0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { status: 'paused', pauseReason: reason, ...patch }, this.now())) {
+            const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+            if (fresh)
+                this.emit(fresh);
+        }
+    }
+    /** The in-flight chunk itself failed (failed / stalled / stopped / provider
+     *  limit / lost): pause AND remember that chunk so Resume retries it — never
+     *  the next one (run 10dedd5a relaunched tickets 4–6 while 1–3 had failed). */
+    pauseFailedChunk(row, reason) {
+        this.pause(row, reason, { retryChunk: Math.max(0, row.next_chunk - 1) });
+    }
+    /** Launch the next chunk (or complete). Failures pause with `launch_rejected:<error>`. */
+    async advance(chainId, head) {
+        const row = (0, milestone_chain_store_1.getChain)(this.db, chainId);
+        if (!row || !(0, milestone_chain_store_1.isActiveChainStatus)(row.status))
+            return;
+        const chunks = (0, milestone_chain_store_1.parseChunks)(row);
+        // A paused chain whose chunk FAILED retries that chunk; otherwise the next.
+        const chunkIndex = row.retry_chunk !== null && row.retry_chunk < row.next_chunk ? row.retry_chunk : row.next_chunk;
+        if (chunkIndex >= chunks.length) {
+            if ((0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { status: 'completed', headBranch: head, currentRailIndex: null, currentRunIds: [], currentDeliveryId: null, pauseReason: null }, this.now())) {
+                const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+                if (fresh)
+                    this.emit(fresh);
+            }
+            return;
+        }
+        const earlierDeliveries = (0, milestone_chain_store_1.parseLaunched)(row).filter((entry) => entry.chunk <= chunkIndex && entry.deliveryId).map((entry) => entry.deliveryId);
+        const multiRepositoryHistory = earlierDeliveries.some((id) => this.io.getDelivery(id)?.executionManifest);
+        if (!multiRepositoryHistory && head && !(await this.branchExistsSafe(head))) {
+            this.pause(row, 'head_missing', { headBranch: head });
+            return;
+        }
+        (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { status: 'waiting', headBranch: head, pauseReason: null }, this.now());
+        const reuse = chunkIndex < row.next_chunk ? this.reusableRailFor(row, chunkIndex) : null;
+        const r = await this.launchChunk(row.milestone_n, chunks, chunkIndex, head, reuse, multiRepositoryHistory ? earlierDeliveries : undefined);
+        const current = (0, milestone_chain_store_1.getChain)(this.db, chainId);
+        if (!current || !(0, milestone_chain_store_1.isActiveChainStatus)(current.status))
+            return;
+        if (!r.ok) {
+            this.pause(current, `launch_rejected:${r.error}`);
+            return;
+        }
+        this.recordLaunched(chainId, r.entry);
+        const fresh = (0, milestone_chain_store_1.getChain)(this.db, chainId);
+        if (fresh)
+            this.emit(fresh);
+    }
+    /**
+     * A chunk settled successfully: advance (launch the next chunk / complete)
+     * when auto-advance is on or nothing is left; otherwise park the chain at a
+     * WAVE CHECKPOINT (`awaiting_approval`) with the head recorded — the user
+     * launches the next rail (resume) or flips auto-advance on.
+     */
+    afterChunkSuccess(chainId, head) {
+        const row = (0, milestone_chain_store_1.getChain)(this.db, chainId);
+        if (!row)
+            return;
+        const remaining = (0, milestone_chain_store_1.parseChunks)(row).length - row.next_chunk;
+        if (row.auto_advance !== 0 || remaining <= 0) {
+            void this.advance(chainId, head);
+            return;
+        }
+        if ((0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { status: 'awaiting_approval', headBranch: head, pauseReason: null }, this.now())) {
+            const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+            if (fresh)
+                this.emit(fresh);
+        }
+    }
+    async branchExistsSafe(branch) {
+        try {
+            return await this.io.branchExists(branch);
+        }
+        catch {
+            return false;
+        }
+    }
+    failureReason(row) {
+        if (row.last_run_outcome === 'provider_limit')
+            return 'provider_limit';
+        if (row.last_run_outcome === 'stalled')
+            return 'chunk_stalled';
+        if (row.last_run_outcome === 'stopped')
+            return 'chunk_stopped';
+        return 'chunk_failed';
+    }
+    /** The delivery-settle chokepoint: a `rail.pr_state` for the in-flight chunk. */
+    handleDeliveryState(snap) {
+        for (const row of (0, milestone_chain_store_1.listActiveChains)(this.db)) {
+            if (row.current_delivery_id !== snap.id)
+                continue;
+            if (snap.decision === 'building')
+                continue;
+            if (SUCCESS_DECISIONS.has(snap.decision)) {
+                const delivered = snap.executionManifest ? null : snap.decision === 'no_changes'
+                    ? row.head_branch
+                    : (snap.branch ?? snap.units.find((u) => u.succeeded && u.branch)?.branch ?? row.head_branch);
+                if (row.status === 'running') {
+                    // Detach the settled chunk first so a duplicate broadcast is inert.
+                    (0, milestone_chain_store_1.updateChain)(this.db, row.id, 'running', { status: 'waiting', currentDeliveryId: null, currentRunIds: [], headBranch: delivered }, this.now());
+                    this.afterChunkSuccess(row.id, delivered);
+                }
+                else {
+                    // Paused (e.g. head_discarded) while the chunk was in flight: record
+                    // the head, never auto-advance — Resume is the user's call.
+                    (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { currentDeliveryId: null, currentRunIds: [], headBranch: delivered }, this.now());
+                }
+                continue;
+            }
+            if (row.status === 'running')
+                this.pauseFailedChunk(row, this.failureReason(row));
+            else
+                (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { currentDeliveryId: null, currentRunIds: [] }, this.now());
+        }
+    }
+    /** Tap for the project's bound broadcast (mirrors MilestoneProgressBroadcaster). */
+    observe(msg) {
+        if (msg.type !== 'rail.pr_state')
+            return;
+        const id = msg.prDeliveryId;
+        if (typeof id !== 'string')
+            return;
+        if (!(0, milestone_chain_store_1.listActiveChains)(this.db).some((row) => row.current_delivery_id === id))
+            return;
+        let snap = null;
+        try {
+            snap = this.io.getDelivery(id);
+        }
+        catch {
+            snap = null;
+        }
+        if (snap)
+            this.handleDeliveryState(snap);
+    }
+    /**
+     * Engine settle fallback (`onLoopRunFinished`). For an isolated chunk this
+     * fires BEFORE the delivery leaves `building` — only the outcome is recorded
+     * (it names the pause reason later). A chunk with NO delivery row (shared-cwd
+     * fallback) settles here: success advances from the current head (no
+     * stacking is possible without a worktree), anything else pauses.
+     */
+    onRunSettled(runId, outcome, stallReason) {
+        // A provider usage limit is its own pause reason (the user waits for the
+        // reset, then resumes) — never lumped in with a generic stall.
+        const recorded = outcome === 'stalled' && stallReason === 'provider_limit' ? 'provider_limit' : outcome;
+        for (const row of (0, milestone_chain_store_1.listActiveChains)(this.db)) {
+            if (!(0, milestone_chain_store_1.parseRunIds)(row).includes(runId))
+                continue;
+            (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { lastRunOutcome: recorded }, this.now());
+            if (row.current_delivery_id)
+                continue;
+            if (row.status !== 'running') {
+                (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { currentRunIds: [] }, this.now());
+                continue;
+            }
+            if (outcome === 'success') {
+                (0, milestone_chain_store_1.updateChain)(this.db, row.id, 'running', { status: 'waiting', currentRunIds: [] }, this.now());
+                this.afterChunkSuccess(row.id, row.head_branch);
+            }
+            else {
+                const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+                if (fresh)
+                    this.pauseFailedChunk(fresh, this.failureReason(fresh));
+            }
+        }
+    }
+    async resume(id) {
+        const row = (0, milestone_chain_store_1.getChain)(this.db, id);
+        if (!row)
+            return { ok: false, status: 404, error: 'chain_not_found' };
+        if (row.status !== 'paused' && row.status !== 'awaiting_approval')
+            return { ok: false, status: 409, error: 'chain_not_paused', detail: `chain is ${row.status}` };
+        if (row.head_branch && !(await this.branchExistsSafe(row.head_branch))) {
+            (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { status: 'paused', pauseReason: 'head_missing' }, this.now());
+            const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+            this.emit(fresh);
+            return { ok: false, status: 409, error: 'head_missing', detail: `branch ${row.head_branch} no longer exists` };
+        }
+        await this.advance(row.id, row.head_branch);
+        const after = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+        return { ok: true, status: 202, chain: (0, milestone_chain_store_1.toChainSnapshot)(after) };
+    }
+    /**
+     * Flip the checkpoint preference on a live chain. Turning it ON while the
+     * chain sits at a checkpoint launches the next chunk immediately.
+     */
+    async setAutoAdvance(id, on) {
+        const row = (0, milestone_chain_store_1.getChain)(this.db, id);
+        if (!row)
+            return { ok: false, status: 404, error: 'chain_not_found' };
+        if (!(0, milestone_chain_store_1.isActiveChainStatus)(row.status))
+            return { ok: false, status: 409, error: 'chain_terminal', detail: `chain is ${row.status}` };
+        (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { autoAdvance: on }, this.now());
+        if (on && row.status === 'awaiting_approval')
+            return this.resume(id);
+        const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+        this.emit(fresh);
+        return { ok: true, status: 200, chain: (0, milestone_chain_store_1.toChainSnapshot)(fresh) };
+    }
+    cancel(id) {
+        const row = (0, milestone_chain_store_1.getChain)(this.db, id);
+        if (!row)
+            return { ok: false, status: 404, error: 'chain_not_found' };
+        if (!(0, milestone_chain_store_1.isActiveChainStatus)(row.status))
+            return { ok: false, status: 409, error: 'chain_terminal', detail: `chain is ${row.status}` };
+        (0, milestone_chain_store_1.updateChain)(this.db, row.id, row.status, { status: 'cancelled' }, this.now());
+        const fresh = (0, milestone_chain_store_1.getChain)(this.db, row.id);
+        this.emit(fresh);
+        return { ok: true, status: 200, chain: (0, milestone_chain_store_1.toChainSnapshot)(fresh) };
+    }
+    /**
+     * Startup: a chain whose in-flight chunk settled while the server was down
+     * replays that settle exactly once (delivery row first, run rows as the
+     * delivery-less fallback); a chunk whose rows vanished pauses `run_lost`.
+     * Call only once the HTTP server is listening (advances launch over loopback).
+     */
+    async recoverOnStartup() {
+        for (const row of (0, milestone_chain_store_1.listActiveChains)(this.db)) {
+            if (row.status !== 'running')
+                continue;
+            if (row.current_delivery_id) {
+                const snap = this.io.getDelivery(row.current_delivery_id);
+                if (!snap) {
+                    this.pauseFailedChunk(row, 'run_lost');
+                    continue;
+                }
+                if (snap.decision !== 'building')
+                    this.handleDeliveryState(snap);
+                continue;
+            }
+            const runIds = (0, milestone_chain_store_1.parseRunIds)(row);
+            if (runIds.length === 0) {
+                this.pauseFailedChunk(row, 'run_lost');
+                continue;
+            }
+            const states = runIds.map((id) => this.io.runState(id));
+            if (states.some((s) => s === null)) {
+                this.pauseFailedChunk(row, 'run_lost');
+                continue;
+            }
+            if (states.every((s) => s.settled)) {
+                const outcome = states.every((s) => s.outcome === 'success') ? 'success' : (states.find((s) => s.outcome !== 'success').outcome ?? 'failed');
+                this.onRunSettled(runIds[0], outcome);
+            }
+        }
+    }
+}
+exports.MilestoneChainManager = MilestoneChainManager;