specrails-desktop 2.12.0 → 2.13.0

package/server/dist/loop-graph.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Loop graph model + validation — the pure core shared by the canvas builder
+ * (`loop-builder-canvas`) and the publish gate (`loops-store.publishLoop`).
+ *
+ * A loop is a directed graph of typed nodes connected by edges. Cycles are
+ * allowed (a loop routes back to an earlier node); the run is bounded by the
+ * graph's `config.maxIterations` + `timeoutMinutes`. This module has NO I/O and
+ * NO provider knowledge — it only describes and validates the shape, so it is
+ * trivially unit-testable and reused verbatim by both the store and the engine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyLoopGraph = emptyLoopGraph;
+exports.validateLoopGraph = validateLoopGraph;
+exports.nodesById = nodesById;
+exports.findStartNode = findStartNode;
+exports.successors = successors;
+exports.interpolateSpec = interpolateSpec;
+/** A minimal, structurally-valid empty graph (used to seed a new Draft). */
+function emptyLoopGraph() {
+    return { nodes: [], edges: [], config: { maxIterations: 10, timeoutMinutes: 30 } };
+}
+/**
+ * Validate a loop graph against the publish-time rules:
+ *  - exactly one `start` node,
+ *  - at least one `end` node (the explicit exit),
+ *  - every edge references existing nodes (no dangling edges),
+ *  - every node is reachable from `start` (no orphan / disconnected nodes),
+ *  - a sane config (maxIterations ≥ 1, timeoutMinutes ≥ 1).
+ *
+ * Returns all errors found (not just the first) so the builder can highlight
+ * every problem at once.
+ */
+function validateLoopGraph(graph) {
+    const errors = [];
+    const nodes = graph.nodes ?? [];
+    const edges = graph.edges ?? [];
+    // ── Start cardinality ──────────────────────────────────────────────────────
+    const starts = nodes.filter((n) => n.type === 'start');
+    if (starts.length === 0) {
+        errors.push({ code: 'NO_START', message: 'The loop must have a Start node.' });
+    }
+    else if (starts.length > 1) {
+        for (const extra of starts.slice(1)) {
+            errors.push({
+                code: 'MULTIPLE_START',
+                message: 'The loop must have exactly one Start node.',
+                nodeId: extra.id,
+            });
+        }
+    }
+    // ── End presence ────────────────────────────────────────────────────────────
+    if (!nodes.some((n) => n.type === 'end')) {
+        errors.push({ code: 'NO_END', message: 'The loop must have at least one End node.' });
+    }
+    // ── Config sanity ─────────────────────────────────────────────────────────────
+    const cfg = graph.config;
+    if (!cfg ||
+        !Number.isInteger(cfg.maxIterations) ||
+        cfg.maxIterations < 1 ||
+        typeof cfg.timeoutMinutes !== 'number' ||
+        cfg.timeoutMinutes < 1) {
+        errors.push({
+            code: 'INVALID_CONFIG',
+            message: 'maxIterations and timeoutMinutes must both be ≥ 1.',
+        });
+    }
+    // ── Dangling edges ────────────────────────────────────────────────────────────
+    const nodeIds = new Set(nodes.map((n) => n.id));
+    for (const e of edges) {
+        if (!nodeIds.has(e.source) || !nodeIds.has(e.target)) {
+            errors.push({
+                code: 'DANGLING_EDGE',
+                message: `Edge "${e.id}" references a node that does not exist.`,
+                edgeId: e.id,
+            });
+        }
+    }
+    // ── Reachability from Start (orphan detection) ──────────────────────────────
+    // Only meaningful with exactly one Start; otherwise the start-cardinality
+    // errors above already explain the shape problem.
+    if (starts.length === 1) {
+        const adjacency = new Map();
+        for (const e of edges) {
+            if (nodeIds.has(e.source) && nodeIds.has(e.target)) {
+                const list = adjacency.get(e.source) ?? [];
+                list.push(e.target);
+                adjacency.set(e.source, list);
+            }
+        }
+        const visited = new Set();
+        const queue = [starts[0].id];
+        visited.add(starts[0].id);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const next of adjacency.get(current) ?? []) {
+                if (!visited.has(next)) {
+                    visited.add(next);
+                    queue.push(next);
+                }
+            }
+        }
+        for (const n of nodes) {
+            if (!visited.has(n.id)) {
+                errors.push({
+                    code: 'ORPHAN_NODE',
+                    message: `Node "${n.id}" is not reachable from Start.`,
+                    nodeId: n.id,
+                });
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+// ── Traversal helpers (used by the execution engine) ─────────────────────────
+function nodesById(graph) {
+    return new Map(graph.nodes.map((n) => [n.id, n]));
+}
+function findStartNode(graph) {
+    return graph.nodes.find((n) => n.type === 'start');
+}
+/** The nodes directly reachable from `nodeId` via an outgoing edge (in edge order). */
+function successors(graph, nodeId) {
+    const byId = nodesById(graph);
+    return graph.edges
+        .filter((e) => e.source === nodeId)
+        .map((e) => byId.get(e.target))
+        .filter((n) => n !== undefined);
+}
+function interpolateSpec(text, spec) {
+    return text.replace(/\{\{\s*spec\.(\w+)\s*\}\}/g, (_match, key) => {
+        // `{{spec.ids}}` → all rail ticket ids as `#1 #2 #3` (used by implement/batch).
+        if (key === 'ids') {
+            const ids = spec?.ticketIds ?? (spec?.id != null ? [spec.id] : []);
+            return ids.map((id) => `#${id}`).join(' ');
+        }
+        const value = spec ? spec[key] : undefined;
+        if (value == null)
+            return '';
+        if (Array.isArray(value))
+            return value.join(', ');
+        return String(value);
+    });
+}

package/server/dist/loop-preview.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SAMPLE_SPEC = void 0;
+exports.previewLoop = previewLoop;
+/**
+ * Dry-run preview: resolve every step's tokens (`{{cmd:*}}`, `{{spec.*}}`,
+ * `{{const:*}}`) and return the EXACT prompt/command text that WOULD be sent —
+ * without spawning anything. Lets the user debug a loop before burning tokens.
+ *
+ * Spec tokens are filled from a fixed SAMPLE spec (the real ticket is only known
+ * at launch), so the preview is labelled "sample data" on the client. Commands +
+ * constants resolve to their real run-time values.
+ */
+const loop_command_catalog_1 = require("./loop-command-catalog");
+const loop_graph_1 = require("./loop-graph");
+const loop_constants_1 = require("./loop-constants");
+/** Stand-in ticket so `{{spec.*}}` resolves to something readable in the preview. */
+exports.SAMPLE_SPEC = {
+    id: 1,
+    ticketIds: [1],
+    title: 'Example spec',
+    description: 'Example description',
+    status: 'todo',
+    priority: 'medium',
+    labels: ['example'],
+    jira_key: 'PROJ-1',
+    jira_url: 'https://example.atlassian.net/browse/PROJ-1',
+};
+/** Reachable-first visit order (then any unreachable nodes), mirroring the run. */
+function visitOrder(graph) {
+    const start = (0, loop_graph_1.findStartNode)(graph);
+    const ordered = [];
+    const seen = new Set();
+    const queue = start ? [start] : [];
+    while (queue.length) {
+        const node = queue.shift();
+        if (seen.has(node.id))
+            continue;
+        seen.add(node.id);
+        ordered.push(node);
+        for (const next of (0, loop_graph_1.successors)(graph, node.id))
+            if (!seen.has(next.id))
+                queue.push(next);
+    }
+    for (const n of graph.nodes ?? [])
+        if (!seen.has(n.id))
+            ordered.push(n);
+    return ordered;
+}
+function previewLoop(graph, opts) {
+    const spec = opts.spec ?? exports.SAMPLE_SPEC;
+    const steps = [];
+    for (const node of visitOrder(graph)) {
+        const label = typeof node.data?.label === 'string' && node.data.label.trim() ? node.data.label.trim() : undefined;
+        let text = null;
+        if (node.type === 'ai-step') {
+            text = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)((0, loop_command_catalog_1.expandCommands)(String(node.data?.prompt ?? ''), { provider: opts.provider, ticketIds: spec.ticketIds, specId: spec.id }), spec), opts.constants);
+        }
+        else if (node.type === 'shell') {
+            text = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)(String(node.data?.command ?? ''), spec), opts.constants);
+        }
+        else if (node.type === 'decider') {
+            text = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)(String(node.data?.goal ?? ''), spec), opts.constants);
+        }
+        if (text !== null)
+            steps.push({ nodeId: node.id, kind: node.type, label, text });
+    }
+    return { steps };
+}

package/server/dist/loop-run-manager.js

@@ -0,0 +1,407 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopRunManager = void 0;
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const db_1 = require("./db");
+const loop_graph_1 = require("./loop-graph");
+const loop_command_catalog_1 = require("./loop-command-catalog");
+const loop_constants_1 = require("./loop-constants");
+const loop_decider_1 = require("./loop-decider");
+const loop_runs_store_1 = require("./loop-runs-store");
+const ai_invocations_1 = require("./ai-invocations");
+const ids_1 = require("./ids");
+const HISTORY_MAX_CHARS = 1500;
+function truncate(s, max = 600) {
+    return s.length > max ? s.slice(0, max) + '…' : s;
+}
+class LoopRunManager {
+    db;
+    broadcast;
+    executors;
+    now;
+    _cancelled = new Set();
+    /** The currently-spawned child per run, so cancel/stop can actually KILL a
+     *  blocked spawn (the cooperative `_cancelled` flag can't interrupt an await). */
+    _activeChild = new Map();
+    constructor(db, broadcast, executors, now = () => Date.now()) {
+        this.db = db;
+        this.broadcast = broadcast;
+        this.executors = executors;
+        this.now = now;
+    }
+    /** Cancel an in-flight run: flag it AND kill the active spawned child so a
+     *  blocked AI Step / Shell returns immediately (the engine then settles
+     *  'stopped' at the next boundary). */
+    cancel(runId) {
+        this._cancelled.add(runId);
+        const child = this._activeChild.get(runId);
+        if (child?.pid) {
+            try {
+                (0, tree_kill_1.default)(child.pid, 'SIGKILL', () => { });
+            }
+            catch { /* already gone */ }
+        }
+    }
+    async run(req) {
+        const runId = req.runId ?? (0, ids_1.newId)();
+        const maxIterations = req.graph.config.maxIterations;
+        const timeoutMs = req.graph.config.timeoutMinutes * 60_000;
+        const deadline = this.now() + timeoutMs;
+        // Optional cost cap (USD). Like maxIterations/timeout, it's a BETWEEN-STEPS
+        // guard: per-step cost is only known when that step's process exits, so the
+        // loop is stopped before the NEXT step once the accumulated total crosses the
+        // cap (may overshoot by at most one step). Honest accuracy caveat: for
+        // non-Claude providers the per-step cost is ESTIMATED (rate card) — see the
+        // fail-open warning below when a step yields no priced cost.
+        const maxCostUsd = typeof req.graph.config.maxCostUsd === 'number' && req.graph.config.maxCostUsd > 0
+            ? req.graph.config.maxCostUsd
+            : undefined;
+        (0, loop_runs_store_1.createLoopRun)(this.db, {
+            id: runId,
+            projectId: req.projectId,
+            loopId: req.loopId,
+            loopName: req.loopName ?? null,
+            railIndex: req.railIndex ?? null,
+            ticketId: req.ticketId ?? null,
+            provider: req.provider,
+            model: req.model,
+            reasoningEffort: req.effort ?? null,
+            iterationLimit: maxIterations,
+            startedAt: new Date(this.now()).toISOString(),
+        });
+        this.broadcast({
+            type: 'loop.run_started',
+            projectId: req.projectId,
+            loopRunId: runId,
+            loopId: req.loopId,
+            railIndex: req.railIndex ?? null,
+        });
+        // Surface the run as a JOB so the full session streams live in the Jobs list
+        // + JobDetail, exactly like implement/ultracode. The job id IS the run id;
+        // createJob is idempotent. Synchronous (before the first await) so the row
+        // exists by the time the launch responds → "View Log" never 404s.
+        const jobCommand = `loop: ${req.loopName ?? req.loopId}${req.ticketId != null ? ` #${req.ticketId}` : ''}`;
+        try {
+            (0, db_1.createJob)(this.db, { id: runId, command: jobCommand, started_at: new Date(this.now()).toISOString() });
+        }
+        catch { /* best-effort; the run still proceeds */ }
+        let seq = 0;
+        let stepNum = 0;
+        // Emit a structured step-boundary event (for a segmented/collapsible client
+        // view) AND a visual divider line in the flat log, so each loop step is a
+        // clearly-delimited section.
+        const emitStep = (kind, title) => {
+            stepNum += 1;
+            try {
+                (0, db_1.appendEvent)(this.db, runId, seq, { event_type: 'loop_step', source: 'stdout', payload: JSON.stringify({ index: stepNum, kind, title }) });
+            }
+            catch { /* best-effort */ }
+            this.broadcast({ type: 'event', jobId: runId, event_type: 'loop_step', source: 'stdout', payload: JSON.stringify({ index: stepNum, kind, title }), seq, timestamp: new Date(this.now()).toISOString() });
+            seq += 1;
+            logLine(`\n━━━━━━ Step ${stepNum} · ${title} ━━━━━━`);
+        };
+        const logLine = (line, source = 'stdout') => {
+            try {
+                (0, db_1.appendEvent)(this.db, runId, seq, { event_type: 'log', source, payload: JSON.stringify({ line }) });
+            }
+            catch { /* events table best-effort */ }
+            this.broadcast({ type: 'log', source, line, timestamp: new Date(this.now()).toISOString(), processId: runId });
+            seq += 1;
+        };
+        // Forward a RAW provider stdout line (claude/codex JSONL) as an `event` —
+        // identical to QueueManager — so JobStatusPanel parses real activity
+        // (thinking/reading/editing/tool steps) instead of staying on "Connecting…".
+        // Non-JSON lines fall back to a plain log line.
+        const onRawLine = (line) => {
+            if (!line)
+                return;
+            let eventType;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed.type === 'string')
+                    eventType = parsed.type;
+            }
+            catch { /* not JSON */ }
+            if (!eventType) {
+                logLine(line);
+                return;
+            }
+            try {
+                (0, db_1.appendEvent)(this.db, runId, seq, { event_type: eventType, source: 'stdout', payload: line });
+            }
+            catch { /* best-effort */ }
+            this.broadcast({ type: 'event', jobId: runId, event_type: eventType, source: 'stdout', payload: line, seq, timestamp: new Date(this.now()).toISOString() });
+            seq += 1;
+        };
+        logLine(`▶ Loop "${req.loopName ?? req.loopId}" started${req.spec?.title ? ` — spec: ${req.spec.title}` : ''}`);
+        console.log(`[loop] start run=${runId} loop=${req.loopId} provider=${req.provider} model=${req.model} nodes=${req.graph.nodes.length} cwd=${req.cwd}`);
+        const byId = (0, loop_graph_1.nodesById)(req.graph);
+        const start = (0, loop_graph_1.findStartNode)(req.graph);
+        let outcome = 'failed';
+        let iteration = 0;
+        let totalCost = 0;
+        let totalTokens = 0;
+        let totalDuration = 0;
+        let aiSessionId;
+        // Fail-open honesty: flips true the first time a cost-bearing step yields no
+        // priced cost while a cap is set (non-Claude estimate / unknown model / a
+        // failed step) → the cap can under-count, so we warn once in the run log.
+        let costUnknownWarned = false;
+        // Built-ins always resolve even if the caller omitted `constants`; custom
+        // values layer on top. Used to expand `{{const:*}}` in every node's text.
+        const constMap = { ...loop_constants_1.BUILTIN_CONSTANTS, ...(req.constants ?? {}) };
+        const history = [];
+        // Backstop against a cycle with no Decider (would otherwise never increment
+        // `iteration`): cap total node executions well above any honest run.
+        const stepCap = (maxIterations + 1) * (req.graph.nodes.length + 2) + 16;
+        let steps = 0;
+        const record = (refSuffix, r) => {
+            totalCost += r.cost ?? 0;
+            // Honest cost-cap caveat: a cost-bearing step that reports no figure means
+            // the cap can't be enforced precisely from here on. Warn once (live).
+            if (maxCostUsd !== undefined && r.cost == null && !costUnknownWarned) {
+                costUnknownWarned = true;
+                logLine('⚠️ A step reported no priced cost (non-Claude estimate / unknown model / failed step) — the cost cap may under-count.', 'stderr');
+            }
+            totalTokens += r.tokens ?? 0;
+            totalDuration += r.durationMs ?? 0;
+            (0, ai_invocations_1.recordInvocation)(this.db, {
+                id: (0, ids_1.newId)(),
+                project_id: req.projectId,
+                provider: r.provider ?? req.provider,
+                surface: 'loop',
+                surface_ref_id: refSuffix,
+                ticket_id: req.ticketId ?? null,
+                status: 'success',
+                started_at: new Date(this.now()).toISOString(),
+                total_cost_usd: r.cost,
+                total_cost_usd_estimated: r.estimated ?? false,
+                tokens_out: r.tokens,
+                model: r.model ?? req.model,
+                loop_run_id: runId,
+            });
+        };
+        const composeHistory = () => {
+            const joined = history.join('\n');
+            return joined.length > HISTORY_MAX_CHARS ? '…' + joined.slice(-HISTORY_MAX_CHARS) : joined;
+        };
+        try {
+            let nodeId = start?.id;
+            let settled = !start; // no start node → fall through to settle as failed
+            if (!start)
+                outcome = 'failed';
+            while (nodeId && !settled) {
+                if (this._cancelled.has(runId)) {
+                    outcome = 'stopped';
+                    break;
+                }
+                if (this.now() > deadline) {
+                    outcome = 'failed';
+                    break;
+                }
+                if (++steps > stepCap) {
+                    outcome = 'max-iterations';
+                    break;
+                }
+                // Cost cap: stop BEFORE the next step once prior steps crossed the budget.
+                if (maxCostUsd !== undefined && totalCost >= maxCostUsd) {
+                    logLine(`\n■ Cost cap reached: $${totalCost.toFixed(4)} ≥ $${maxCostUsd.toFixed(2)} — stopping the loop.`, 'stderr');
+                    outcome = 'max-cost';
+                    break;
+                }
+                const node = byId.get(nodeId);
+                if (!node) {
+                    outcome = 'failed';
+                    break;
+                }
+                const succs = (0, loop_graph_1.successors)(req.graph, node.id);
+                // The RAIL governs provider/model/effort for the whole run — nodes do
+                // NOT override (decided in design: "lo que pongamos en el rail manda").
+                const nodeProvider = req.provider;
+                const nodeModel = req.model;
+                const nodeEffort = req.effort;
+                // User-given step name (shown in the run log header); falls back per-kind.
+                const nodeLabel = String(node.data?.label ?? '').trim();
+                switch (node.type) {
+                    case 'start':
+                        nodeId = succs[0]?.id;
+                        break;
+                    case 'end':
+                        outcome = node.data?.outcome === 'failure' ? 'failed' : 'success';
+                        settled = true;
+                        break;
+                    case 'ai-step': {
+                        // Expand magic commands FIRST — `{{cmd:implement}}` becomes the
+                        // NATIVE per-provider invocation (claude `/specrails:implement #<id>
+                        // --yes`, codex `$implement #<id> --yes`) — then resolve `{{spec.*}}`
+                        // data tokens and finally `{{const:*}}` library constants.
+                        const rawTemplate = String(node.data?.prompt ?? '');
+                        const base = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)((0, loop_command_catalog_1.expandCommands)(rawTemplate, { provider: nodeProvider, ticketIds: req.spec?.ticketIds, specId: req.spec?.id }), req.spec), constMap);
+                        const prompt = history.length > 0 ? `${base}\n\n---\nContext from previous iterations:\n${composeHistory()}` : base;
+                        emitStep('ai-step', `🤖 ${nodeLabel || 'AI Step'} (${nodeProvider}/${nodeModel}${nodeEffort ? `, effort: ${nodeEffort}` : ''})`);
+                        // Show the authored template AND the actual COMMAND sent. For magic
+                        // commands this is the short native invocation (so it's plainly visible
+                        // that `/specrails:implement` ran); a long free-text prompt is capped.
+                        logLine(`Template: ${rawTemplate.length > 1000 ? rawTemplate.slice(0, 1000) + '…' : rawTemplate}`);
+                        logLine(`Command: ${base.length > 2000 ? base.slice(0, 2000) + '…(truncated)' : base}`);
+                        const res = await this.executors.runAiStep({ prompt, sessionId: aiSessionId, provider: nodeProvider, model: nodeModel, effort: nodeEffort, cwd: req.cwd, repoDir: req.repoDir, onLine: logLine, onRawLine, onSpawn: (c) => this._activeChild.set(runId, c) });
+                        this._activeChild.delete(runId);
+                        if (res.sessionId)
+                            aiSessionId = res.sessionId;
+                        history.push(`AI Step: ${truncate(res.text)}`);
+                        record(`loop:${runId}`, res);
+                        nodeId = succs[0]?.id;
+                        break;
+                    }
+                    case 'shell': {
+                        const command = (0, loop_constants_1.resolveConstants)((0, loop_graph_1.interpolateSpec)(String(node.data?.command ?? ''), req.spec), constMap);
+                        emitStep('shell', `⚡ ${nodeLabel || 'Shell'}`);
+                        logLine(`$ ${command}`);
+                        const sh = await this.executors.runShell({ command, cwd: req.cwd, onLine: logLine, onSpawn: (c) => this._activeChild.set(runId, c) });
+                        this._activeChild.delete(runId);
+                        logLine(`(exit ${sh.exitCode})`);
+                        totalDuration += sh.durationMs ?? 0;
+                        history.push(`Shell \`${command}\` exit=${sh.exitCode}: ${truncate(sh.stdout || sh.stderr)}`);
+                        nodeId = succs[0]?.id;
+                        break;
+                    }
+                    case 'decider': {
+                        if (iteration >= maxIterations) {
+                            outcome = 'max-iterations';
+                            settled = true;
+                            break;
+                        }
+                        iteration += 1;
+                        const goal = (0, loop_constants_1.resolveConstants)(String(node.data?.goal ?? 'The loop goal is met.'), constMap);
+                        emitStep('decider', `🔍 ${nodeLabel || 'Loop Decider'} (iteration ${iteration})`);
+                        logLine(`Goal: ${goal}`);
+                        const dec = await this.executors.runDecider({
+                            systemPrompt: (0, loop_decider_1.buildDeciderSystemPrompt)(),
+                            userPrompt: (0, loop_decider_1.buildDeciderUserPrompt)({ goal, history }),
+                            provider: nodeProvider,
+                            model: nodeModel,
+                            effort: nodeEffort,
+                            cwd: req.cwd,
+                            repoDir: req.repoDir,
+                            onLine: logLine,
+                            onRawLine,
+                            onSpawn: (c) => this._activeChild.set(runId, c),
+                        });
+                        this._activeChild.delete(runId);
+                        record(`loop:${runId}:decider`, dec);
+                        logLine(`Decision: ${dec.continue ? 'continue' : 'stop'} — ${dec.reasoning}`);
+                        history.push(`Decider: ${dec.continue ? 'continue' : 'stop'} — ${dec.reasoning}`);
+                        (0, loop_runs_store_1.updateLoopRunCounters)(this.db, runId, {
+                            iterationCount: iteration,
+                            totalCostUsd: totalCost,
+                            totalTokens,
+                            totalDurationMs: totalDuration,
+                        });
+                        this.broadcast({
+                            type: 'loop.run_progress',
+                            projectId: req.projectId,
+                            loopRunId: runId,
+                            iteration,
+                            activeNode: node.id,
+                            reasoning: dec.reasoning,
+                        });
+                        // Route by the edge's explicit `branch` (the Decider's two named
+                        // source handles: 'continue' / 'stop'). Legacy graphs authored before
+                        // labeled branches carry no `branch` — fall back to the original
+                        // successor-node-type heuristic (continue → first non-end, stop →
+                        // first end) so old loops keep running identically.
+                        const out = req.graph.edges.filter((e) => e.source === node.id);
+                        const branchTarget = (b) => out.find((e) => e.branch === b)?.target;
+                        const ends = succs.filter((n) => n.type === 'end');
+                        const conts = succs.filter((n) => n.type !== 'end');
+                        if (dec.continue) {
+                            const target = branchTarget('continue') ?? conts[0]?.id;
+                            if (target)
+                                nodeId = target;
+                            else {
+                                outcome = 'success';
+                                settled = true;
+                            }
+                        }
+                        else {
+                            const target = branchTarget('stop') ?? ends[0]?.id;
+                            if (target)
+                                nodeId = target;
+                            else {
+                                outcome = 'success';
+                                settled = true;
+                            }
+                        }
+                        break;
+                    }
+                    case 'condition':
+                        // v1: AND/OR branching is not yet evaluated — follow the first edge.
+                        nodeId = succs[0]?.id;
+                        break;
+                    default:
+                        nodeId = succs[0]?.id;
+                }
+                // Ran off the end of the graph without an explicit End node.
+                if (nodeId === undefined && !settled) {
+                    outcome = 'success';
+                    settled = true;
+                }
+            }
+        }
+        catch (err) {
+            outcome = 'failed';
+            console.error(`[loop] run=${runId} traversal threw:`, err);
+            logLine(`error: ${err?.message ?? String(err)}`, 'stderr');
+        }
+        console.log(`[loop] settle run=${runId} outcome=${outcome} iterations=${iteration} cost=$${totalCost.toFixed(4)}`);
+        (0, loop_runs_store_1.finishLoopRun)(this.db, runId, {
+            outcome,
+            finishedAt: new Date(this.now()).toISOString(),
+            counters: { iterationCount: iteration, totalCostUsd: totalCost, totalTokens, totalDurationMs: totalDuration },
+        });
+        // Settle the backing job so the Jobs list + JobDetail reflect the final
+        // status, and emit job.finalized so an open JobDetail re-fetches + stops the
+        // live stream (mirrors QueueManager).
+        const jobStatus = outcome === 'success' ? 'completed' : outcome === 'stopped' ? 'canceled' : 'failed';
+        logLine(`\n■ Loop finished: ${outcome} — ${iteration} iteration${iteration === 1 ? '' : 's'}, $${totalCost.toFixed(4)}`);
+        try {
+            (0, db_1.finishJob)(this.db, runId, {
+                exit_code: outcome === 'success' ? 0 : 1,
+                status: jobStatus,
+                total_cost_usd: totalCost,
+                tokens_out: totalTokens,
+                duration_ms: totalDuration,
+                num_turns: iteration,
+            });
+        }
+        catch { /* best-effort */ }
+        this.broadcast({
+            type: 'job.finalized',
+            projectId: req.projectId,
+            jobId: runId,
+            status: jobStatus,
+            totals: {
+                tokens_in: 0,
+                tokens_out: totalTokens,
+                tokens_cache_read: 0,
+                tokens_cache_create: 0,
+                total_cost_usd: totalCost,
+                num_turns: iteration,
+            },
+            timestamp: new Date(this.now()).toISOString(),
+        });
+        this.broadcast({
+            type: 'loop.run_completed',
+            projectId: req.projectId,
+            loopRunId: runId,
+            railIndex: req.railIndex ?? null,
+            status: outcome,
+            ticketIds: req.ticketId != null ? [req.ticketId] : [],
+        });
+        return { runId, outcome, iterations: iteration, totalCostUsd: totalCost };
+    }
+}
+exports.LoopRunManager = LoopRunManager;