specrails-desktop 2.12.0 → 2.13.0

package/server/dist/mobile/mobile-router.js

@@ -134,6 +134,17 @@ function createMobileRouter(deps) {
             return;
         void forward(res, 'GET', `/api/projects/${encodeURIComponent(pid)}/jobs/${encodeURIComponent(jid)}`, '');
     });
+    // rails-as-loops reads: the global Loop catalog (for the mobile loop picker)
+    // and per-project loop-run state (the running surface — a loop run has no jobId
+    // so it can't be tailed via /jobs/:id). 404s downstream when Loops are disabled.
+    v1.get('/loops', (_req, res) => { void forward(res, 'GET', '/api/loops', ''); });
+    v1.get('/loops/factory', (_req, res) => { void forward(res, 'GET', '/api/loops/factory', ''); });
+    v1.get('/projects/:pid/loop-runs/:id', (req, res) => {
+        const pid = seg(req.params.pid), rid = seg(req.params.id);
+        if (!validate(res, [pid, PID_RE], [rid, JOBID_RE]))
+            return;
+        void forward(res, 'GET', `/api/projects/${encodeURIComponent(pid)}/loop-runs/${encodeURIComponent(rid)}`, '');
+    });
     v1.get('/projects/:pid/tickets/:tid/spending-summary', (req, res) => {
         const pid = seg(req.params.pid), tid = seg(req.params.tid);
         if (!validate(res, [pid, PID_RE], [tid, NUM_RE]))
@@ -183,6 +194,14 @@ function createMobileRouter(deps) {
             narrowed.aiEngine = b.aiEngine;
         if (typeof b.model === 'string')
             narrowed.model = b.model; // ultracode model
+        // rails-as-loops: let a mobile client launch a chosen Loop (factory or custom).
+        // Additive — the frozen bare-`mode` path is untouched (a v1 client sends no loopId).
+        if (typeof b.loopId === 'string')
+            narrowed.loopId = b.loopId;
+        if (b.reasoning_effort === 'low' || b.reasoning_effort === 'medium' || b.reasoning_effort === 'high')
+            narrowed.reasoning_effort = b.reasoning_effort;
+        if (typeof b.interactive === 'boolean')
+            narrowed.interactive = b.interactive;
         void forward(res, 'POST', `/api/projects/${encodeURIComponent(pid)}/rails/${encodeURIComponent(i)}/launch`, '', narrowed);
     });
     v1.put('/projects/:pid/rails/:i/engine', (req, res) => {
@@ -375,6 +394,9 @@ exports.MOBILE_ALLOWLIST = [
     { method: 'GET', path: '/v1/projects/:pid/tickets/:tid' },
     { method: 'GET', path: '/v1/projects/:pid/jobs' },
     { method: 'GET', path: '/v1/projects/:pid/jobs/:jid' },
+    { method: 'GET', path: '/v1/loops' },
+    { method: 'GET', path: '/v1/loops/factory' },
+    { method: 'GET', path: '/v1/projects/:pid/loop-runs/:id' },
     { method: 'GET', path: '/v1/projects/:pid/queue' },
     { method: 'GET', path: '/v1/projects/:pid/rails' },
     { method: 'GET', path: '/v1/projects/:pid/activity' },

package/server/dist/mobile/mobile-ws.js

@@ -27,7 +27,15 @@ function topicFor(type) {
         case 'rail.job_started':
         case 'rail.job_stopped':
         case 'rail.job_completed':
-        case 'rail.updated': return 'rails';
+        case 'rail.updated':
+        // rails-as-loops: loop runs (no queue job) report their lifecycle via the
+        // loop.run_* family. Map them onto the EXISTING 'rails' topic (frozen-safe —
+        // the companion's subscribe set is unchanged; an old v1 client ignores the
+        // unknown `loop.run_*` types harmlessly, a new client mirrors the run).
+        case 'loop.run_started':
+        case 'loop.run_progress':
+        case 'loop.run_stopped':
+        case 'loop.run_completed': return 'rails';
         case 'spending.invalidated': return 'spending';
         case 'chat_stream':
         case 'chat_done':
@@ -59,6 +67,14 @@ const LEGACY_WIRE_TYPES = {
     desktop_daily_budget_exceeded: 'hub_daily_budget_exceeded',
 };
 function toMobileWire(msg) {
+    // SECURITY: loop.run_progress carries `reasoning` — free-text LLM output that
+    // the path-only `redact()` does NOT scrub for repo content. Drop it at the
+    // mobile boundary (forward only iteration/activeNode); it's the one field that
+    // would leak more than any existing rail.* frame. Forward everything else.
+    if (msg.type === 'loop.run_progress') {
+        const { reasoning: _drop, ...rest } = msg;
+        return rest;
+    }
     const legacyType = LEGACY_WIRE_TYPES[msg.type];
     if (!legacyType)
         return msg;

package/server/dist/project-registry.js

@@ -32,6 +32,9 @@ const workspace_resolution_1 = require("./workspace-resolution");
 const workspace_manager_1 = require("./workspace-manager");
 const ticket_store_1 = require("./ticket-store");
 const jira_sync_manager_1 = require("./jira/jira-sync-manager");
+const loop_run_manager_1 = require("./loop-run-manager");
+const loop_executors_1 = require("./loop-executors");
+const loop_runs_store_1 = require("./loop-runs-store");
 const rails_store_1 = require("./rails-store");
 const desktop_db_1 = require("./desktop-db");
 const config_1 = require("./config");
@@ -626,7 +629,106 @@ class ProjectRegistry {
             // projects instead of a per-project profile.
             contextPool: this._browserContextPool,
         });
-        const ctx = { project, db, queueManager, chatManager, setupManager, proposalManager, agentRefineManager, fileSummaryManager, specLauncherManager, ticketWatcher, browserCaptureManager, jiraSyncManager, broadcast: boundBroadcast, railJobs };
+        // ── Loops engine (the Loops feature) ──────────────────────────────────────
+        const railLoopRuns = new Map();
+        // A restart kills any in-flight loop process, so reconcile orphan 'running'
+        // rows to terminal — otherwise they keep the loop un-editable (isRunning 409).
+        try {
+            const orphans = (0, loop_runs_store_1.reconcileOrphanLoopRuns)(db, new Date().toISOString());
+            if (orphans > 0)
+                console.log(`[loops] reconciled ${orphans} orphan loop run(s) for ${project.slug}`);
+        }
+        catch { /* non-fatal */ }
+        const loopRunManager = new loop_run_manager_1.LoopRunManager(db, boundBroadcast, (0, loop_executors_1.createLoopExecutors)());
+        const getTicketSpec = (ticketId) => {
+            try {
+                const exec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path });
+                const ticketFile = exec.relocated ? exec.ticketsPath : (0, ticket_store_1.resolveTicketStoragePath)(project.path);
+                const t = (0, ticket_store_1.readStore)(ticketFile).tickets[String(ticketId)];
+                if (!t)
+                    return undefined;
+                // Expose every field a loop prompt can reference via `{{spec.*}}`.
+                return {
+                    id: t.id,
+                    title: t.title,
+                    description: t.description,
+                    status: t.status,
+                    priority: t.priority,
+                    labels: t.labels,
+                    jira_key: t.jira_key ?? null,
+                    jira_url: t.jira_url ?? null,
+                };
+            }
+            catch {
+                return undefined;
+            }
+        };
+        // Releases a finished loop run's tickets + rail slots. The engine already
+        // emitted loop.run_completed; this mirrors onJobFinished's ticket/rail
+        // release (kept separate so the critical job path is untouched).
+        const onLoopRunFinished = (runId, outcome) => {
+            const meta = railLoopRuns.get(runId);
+            if (!meta)
+                return;
+            railLoopRuns.delete(runId);
+            const ticketIds = meta.ticketIds;
+            if (ticketIds.length === 0)
+                return;
+            const status = outcome === 'success' ? 'completed' : outcome === 'stopped' ? 'canceled' : 'failed';
+            try {
+                const exec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path });
+                const ticketFile = exec.relocated ? exec.ticketsPath : (0, ticket_store_1.resolveTicketStoragePath)(project.path);
+                const now = new Date().toISOString();
+                let changedIds = [];
+                const store = (0, ticket_store_1.mutateStore)(ticketFile, (s) => {
+                    changedIds = (0, ticket_store_1.applyJobOutcomeToTickets)(s, ticketIds, status, now);
+                });
+                for (const tid of changedIds) {
+                    const ticket = store.tickets[String(tid)];
+                    if (!ticket)
+                        continue;
+                    boundBroadcast({
+                        type: 'ticket_updated',
+                        ticket: ticket,
+                        projectId: project.id,
+                        timestamp: ticket.updated_at,
+                    });
+                }
+                try {
+                    const needsReviewIds = ticketIds.filter((tid) => store.tickets[String(tid)]?.needs_review === true);
+                    jiraSyncManager.onJobOutcome({ ticketIds, status, jobId: runId, costUsd: null, durationMs: null, needsReviewIds });
+                }
+                catch (err) {
+                    console.error('[project-registry] jira loop onJobOutcome failed:', err);
+                }
+            }
+            catch (err) {
+                console.error('[project-registry] failed to apply loop outcome to tickets:', err);
+            }
+            try {
+                for (const rail of (0, rails_store_1.getRails)(db)) {
+                    const remaining = rail.ticketIds.filter((id) => !ticketIds.includes(id));
+                    if (remaining.length === rail.ticketIds.length)
+                        continue;
+                    (0, rails_store_1.setRailTickets)(db, rail.railIndex, remaining, rail.mode, rail.profileName, rail.aiEngine);
+                    boundBroadcast({
+                        type: 'rail.updated',
+                        projectId: project.id,
+                        railIndex: rail.railIndex,
+                        changed: 'tickets',
+                        ticketIds: remaining,
+                        name: rail.name ?? null,
+                        mode: rail.mode,
+                        profileName: rail.profileName ?? null,
+                        aiEngine: rail.aiEngine ?? null,
+                    });
+                }
+            }
+            catch (err) {
+                console.error('[project-registry] failed to release rail tickets after loop run:', err);
+            }
+        };
+        const ctx = { project, db, queueManager, chatManager, setupManager, proposalManager, agentRefineManager, fileSummaryManager, specLauncherManager, ticketWatcher, browserCaptureManager, jiraSyncManager, broadcast: boundBroadcast, railJobs, loopRunManager, railLoopRuns, onLoopRunFinished, getTicketSpec, desktopDb: this._desktopDb };
         this._contexts.set(project.id, ctx);
         return ctx;
     }

package/server/dist/project-router-jobs.js

@@ -101,8 +101,18 @@ function registerJobsRoutes(deps) {
         res.json({ model, provider, allowed, providers: project.providers });
     });
     router.delete('/:projectId/jobs/:id', (req, res) => {
+        const id = req.params.id;
+        const c = ctx(req);
+        // A loop run is backed by a job row but is NOT a QueueManager job — it is
+        // driven by the LoopRunManager. Cancel it through the engine (which settles
+        // it 'stopped' → finishJob('canceled') + releases the rail's tickets).
+        if (c.railLoopRuns?.has(id)) {
+            c.loopRunManager?.cancel(id);
+            res.json({ ok: true, status: 'canceling' });
+            return;
+        }
         try {
-            const result = ctx(req).queueManager.cancel(req.params.id);
+            const result = c.queueManager.cancel(id);
             res.json({ ok: true, status: result });
         }
         catch (err) {

package/server/dist/project-router-loop-runs.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLoopRunRoutes = registerLoopRunRoutes;
+const feature_flags_1 = require("./feature-flags");
+const loops_store_1 = require("./loops-store");
+const loop_runs_store_1 = require("./loop-runs-store");
+const loop_constants_1 = require("./loop-constants");
+const providers_1 = require("./providers");
+const provider_selection_1 = require("./provider-selection");
+const workspace_resolution_1 = require("./workspace-resolution");
+const loop_command_catalog_1 = require("./loop-command-catalog");
+const ids_1 = require("./ids");
+const VALID_REASONING_EFFORTS = new Set(['low', 'medium', 'high']);
+function registerLoopRunRoutes(deps) {
+    const { router, ctx } = deps;
+    // GET a single loop run's live/terminal state. Backs the companion's running
+    // surface (a loop run has no jobId, so it can't be tailed via /jobs/:id).
+    router.get('/:projectId/loop-runs/:id', (req, res) => {
+        if (!(0, feature_flags_1.isLoopsEnabled)()) {
+            res.status(404).json({ error: 'Not Found' });
+            return;
+        }
+        const c = ctx(req);
+        const run = (0, loop_runs_store_1.getLoopRun)(c.db, req.params.id);
+        if (!run || run.project_id !== c.project.id) {
+            res.status(404).json({ error: 'Loop run not found' });
+            return;
+        }
+        res.json({ loopRun: run });
+    });
+    router.post('/:projectId/loop-runs', (req, res) => {
+        if (!(0, feature_flags_1.isLoopsEnabled)()) {
+            res.status(404).json({ error: 'Not Found' });
+            return;
+        }
+        const c = ctx(req);
+        const body = req.body ?? {};
+        const { loopId, aiEngine, provider: providerAlias, reasoning_effort } = body;
+        if (typeof loopId !== 'string' || !loopId) {
+            res.status(400).json({ error: 'loopId is required' });
+            return;
+        }
+        const loop = (0, loops_store_1.getLoop)(c.desktopDb, loopId);
+        if (!loop) {
+            res.status(404).json({ error: 'Loop not found' });
+            return;
+        }
+        if (loop.status !== 'published') {
+            res.status(400).json({ error: 'Loop must be published before it can run' });
+            return;
+        }
+        let effort;
+        if (reasoning_effort !== undefined && reasoning_effort !== null) {
+            if (typeof reasoning_effort !== 'string' || !VALID_REASONING_EFFORTS.has(reasoning_effort)) {
+                res.status(400).json({ error: 'reasoning_effort must be one of: low, medium, high' });
+                return;
+            }
+            effort = reasoning_effort;
+        }
+        const check = (0, provider_selection_1.validateRequestedProvider)(c.project, aiEngine ?? providerAlias);
+        if (!check.ok) {
+            res.status(400).json({ error: check.error });
+            return;
+        }
+        const provider = check.provider;
+        // claude-only guard (e.g. a loop that uses {{cmd:ultracode}}).
+        const promptsText = loop.graph.nodes
+            .filter((n) => n.type === 'ai-step')
+            .map((n) => String(n.data?.prompt ?? ''))
+            .join('\n');
+        if ((0, loop_command_catalog_1.referencesClaudeOnlyCommand)(promptsText) && provider !== 'claude') {
+            res.status(400).json({ error: 'This loop uses a Claude-only command and requires the Claude provider' });
+            return;
+        }
+        const model = (0, providers_1.getAdapter)(provider).defaultModel();
+        const exec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: c.project.slug, path: c.project.path });
+        const runId = (0, ids_1.newId)();
+        c.loopRunManager
+            .run({
+            runId,
+            loopId,
+            loopName: loop.name,
+            graph: loop.graph,
+            projectId: c.project.id,
+            cwd: exec.cwd,
+            repoDir: exec.relocated ? exec.repoDir : undefined,
+            railIndex: null,
+            ticketId: null,
+            spec: undefined,
+            constants: (0, loop_constants_1.loadConstantMap)(c.desktopDb),
+            provider,
+            model,
+            effort,
+        })
+            .then((r) => c.onLoopRunFinished(r.runId, r.outcome))
+            .catch((err) => {
+            console.error('[loop-runs] standalone run failed:', err);
+            c.onLoopRunFinished(runId, 'failed');
+        });
+        res.status(202).json({ loopRunId: runId });
+    });
+}

package/server/dist/project-router.js

@@ -18,6 +18,7 @@ const project_router_setup_1 = require("./project-router-setup");
 const project_router_tickets_1 = require("./project-router-tickets");
 const project_router_terminals_1 = require("./project-router-terminals");
 const project_router_settings_1 = require("./project-router-settings");
+const project_router_loop_runs_1 = require("./project-router-loop-runs");
 // Re-export the spec helpers from their new home so existing importers
 // (`import { ... } from './project-router'`) keep working unchanged.
 var project_router_helpers_1 = require("./project-router-helpers");
@@ -115,5 +116,6 @@ function createProjectRouter(registry) {
     (0, project_router_tickets_1.registerTicketsRoutes)(deps);
     (0, project_router_terminals_1.registerTerminalsRoutes)(deps);
     (0, project_router_settings_1.registerSettingsRoutes)(deps);
+    (0, project_router_loop_runs_1.registerLoopRunRoutes)(deps);
     return router;
 }

package/server/dist/providers/claude-adapter.js

@@ -68,6 +68,9 @@ function commonFlagsFor(opts) {
         ...COMMON_FLAGS,
         '--setting-sources',
         opts.loadUserEnv ? 'user,project,local' : 'project,local',
+        // Native reasoning-effort flag (claude CLI accepts low|medium|high|xhigh|max).
+        // Emitted only when requested; absent ⇒ the CLI's default effort.
+        ...(opts.reasoning_effort ? ['--effort', opts.reasoning_effort] : []),
     ];
 }
 function buildClaudeArgs(action, opts) {
@@ -313,6 +316,7 @@ exports.claudeAdapter = {
         profileEnvSupport: true,
         systemPromptArg: true,
         persistentStdin: true,
+        supportsReasoningEffort: true,
     },
     modelCatalog: () => CLAUDE_MODELS,
     defaultModel: () => 'sonnet',

package/server/dist/providers/codex-adapter.js

@@ -66,6 +66,10 @@ function buildCodexArgs(action, opts) {
             args.push('exec', '--json', ...SANDBOX_FLAGS, SKIP_GIT_CHECK);
             args.push(opts.prompt);
             args.push('--model', opts.model);
+            // Native reasoning effort (codex 0.139+). String value is quoted to match
+            // the `-c key="value"` override form used elsewhere in this adapter.
+            if (opts.reasoning_effort)
+                args.push('-c', `model_reasoning_effort="${opts.reasoning_effort}"`);
             if (opts.extraArgs)
                 args.push(...opts.extraArgs);
             return args;
@@ -77,6 +81,10 @@ function buildCodexArgs(action, opts) {
             args.push('exec', '--json', ...SANDBOX_FLAGS, SKIP_GIT_CHECK);
             args.push(fold(opts.systemPrompt, opts.prompt));
             args.push('--model', opts.model);
+            // Native reasoning effort (codex 0.139+). String value is quoted to match
+            // the `-c key="value"` override form used elsewhere in this adapter.
+            if (opts.reasoning_effort)
+                args.push('-c', `model_reasoning_effort="${opts.reasoning_effort}"`);
             if (opts.extraArgs)
                 args.push(...opts.extraArgs);
             return args;
@@ -92,6 +100,10 @@ function buildCodexArgs(action, opts) {
             args.push(opts.sessionId);
             args.push(opts.prompt);
             args.push('--model', opts.model);
+            // Native reasoning effort (codex 0.139+). String value is quoted to match
+            // the `-c key="value"` override form used elsewhere in this adapter.
+            if (opts.reasoning_effort)
+                args.push('-c', `model_reasoning_effort="${opts.reasoning_effort}"`);
             if (opts.extraArgs)
                 args.push(...opts.extraArgs);
             return args;
@@ -104,6 +116,10 @@ function buildCodexArgs(action, opts) {
             args.push(opts.sessionId);
             args.push(fold(opts.systemPrompt, opts.prompt));
             args.push('--model', opts.model);
+            // Native reasoning effort (codex 0.139+). String value is quoted to match
+            // the `-c key="value"` override form used elsewhere in this adapter.
+            if (opts.reasoning_effort)
+                args.push('-c', `model_reasoning_effort="${opts.reasoning_effort}"`);
             if (opts.extraArgs)
                 args.push(...opts.extraArgs);
             return args;
@@ -123,6 +139,10 @@ function buildCodexArgs(action, opts) {
             args.push('exec', '--json', ...RAIL_SANDBOX_FLAGS, SKIP_GIT_CHECK);
             args.push(fold(opts.systemPrompt, opts.prompt));
             args.push('--model', opts.model);
+            // Native reasoning effort (codex 0.139+). String value is quoted to match
+            // the `-c key="value"` override form used elsewhere in this adapter.
+            if (opts.reasoning_effort)
+                args.push('-c', `model_reasoning_effort="${opts.reasoning_effort}"`);
             if (opts.extraArgs)
                 args.push(...opts.extraArgs);
             return args;
@@ -288,6 +308,7 @@ exports.codexAdapter = {
         nativeOtelEnv: false,
         profileEnvSupport: true,
         systemPromptArg: false,
+        supportsReasoningEffort: true,
     },
     modelCatalog: () => CODEX_MODELS,
     defaultModel: () => 'gpt-5.5',

package/server/dist/providers/gemini-adapter.js

@@ -229,6 +229,10 @@ exports.geminiAdapter = {
         nativeOtelEnv: true,
         profileEnvSupport: true,
         systemPromptArg: false,
+        // gemini-cli has NO per-invocation reasoning-effort flag (thinking levels
+        // require settings.json `thinkingConfig` + custom model aliases, not a
+        // per-spawn arg), so effort is not offered and the adapter ignores it.
+        supportsReasoningEffort: false,
     },
     modelCatalog: () => GEMINI_MODELS,
     defaultModel: () => 'gemini-3.5-flash',

package/server/dist/rails-router.js

@@ -6,10 +6,21 @@ const rails_store_1 = require("./rails-store");
 const queue_manager_1 = require("./queue-manager");
 const provider_selection_1 = require("./provider-selection");
 const feature_flags_1 = require("./feature-flags");
-const VALID_MODES = new Set(['implement', 'batch-implement', 'ultracode']);
+const loops_store_1 = require("./loops-store");
+const loop_runs_store_1 = require("./loop-runs-store");
+const providers_1 = require("./providers");
+const workspace_resolution_1 = require("./workspace-resolution");
+const loop_factory_1 = require("./loop-factory");
+const loop_constants_1 = require("./loop-constants");
+const loop_command_catalog_1 = require("./loop-command-catalog");
+const ids_1 = require("./ids");
+const VALID_MODES = new Set(['implement', 'batch-implement', 'ultracode', 'loop']);
 // Models the ultracode picker exposes (Claude aliases). Mirrors the client
 // RailModelSelector options and the project-router orchestrator-model allow-list.
 const VALID_ULTRACODE_MODELS = new Set(['haiku', 'sonnet', 'opus']);
+// Reasoning-effort tiers a loop launch may request (mirrors the client selector
+// + the provider adapters' supported values).
+const VALID_REASONING_EFFORTS = new Set(['low', 'medium', 'high']);
 function createRailsRouter() {
     const router = (0, express_1.Router)({ mergeParams: true });
     function ctx(req) {
@@ -46,7 +57,19 @@ function createRailsRouter() {
             for (const [jobId, meta] of c.railJobs.entries()) {
                 activeJobs[meta.railIndex] = { jobId, mode: meta.mode };
             }
-            res.json({ rails, activeJobs });
+            // Active loop runs (Loops mode) so clients can reconcile a 'running' rail
+            // that's executing a loop rather than a queue job. Enriched from the
+            // loop_runs row with the loop identity + resolved provider/model so a
+            // mirror (e.g. the mobile companion) can label the run instead of showing a
+            // stale `mode`/null engine — these never land on the rail row itself.
+            const activeLoopRuns = {};
+            for (const [runId, meta] of c.railLoopRuns.entries()) {
+                const run = (0, loop_runs_store_1.getLoopRun)(c.db, runId);
+                activeLoopRuns[meta.railIndex] = run
+                    ? { loopRunId: runId, loopId: run.loop_id, loopName: run.loop_name, provider: run.provider, model: run.model, iteration: run.iteration_count }
+                    : { loopRunId: runId };
+            }
+            res.json({ rails, activeJobs, activeLoopRuns });
         }
         catch (err) {
             console.error('[rails-router] get rails error:', err);
@@ -190,9 +213,26 @@ function createRailsRouter() {
             res.status(400).json({ error: 'Invalid rail index' });
             return;
         }
-        const { mode = 'implement', profileName, aiEngine, model, interactive } = req.body ?? {};
+        let { mode = 'implement' } = req.body ?? {};
+        const { profileName, aiEngine, model, interactive, loopId, reasoning_effort } = req.body ?? {};
+        // rails-as-loops: a FACTORY loop id (`factory:implement` etc.) maps to its
+        // legacy mode and runs through the EXISTING engine (QueueManager) — the rail
+        // "picks a Loop", the plumbing is unchanged. A CUSTOM loop id keeps mode='loop'
+        // (LoopRunManager). Legacy callers that still send a bare `mode` are unchanged.
+        if (typeof loopId === 'string' && (0, loop_factory_1.isFactoryLoopId)(loopId)) {
+            const fmode = (0, loop_factory_1.factoryLoopMode)(loopId);
+            if (!fmode) {
+                res.status(404).json({ error: 'Factory loop not found' });
+                return;
+            }
+            mode = fmode;
+        }
         if (!VALID_MODES.has(mode)) {
-            res.status(400).json({ error: 'mode must be "implement", "batch-implement" or "ultracode"' });
+            res.status(400).json({ error: 'mode must be "implement", "batch-implement", "ultracode" or "loop"' });
+            return;
+        }
+        if (mode === 'loop' && !(0, feature_flags_1.isLoopsEnabled)()) {
+            res.status(403).json({ error: 'Loops are disabled on this server' });
             return;
         }
         // Ultracode model picker: optional, validated against the allow-list.
@@ -262,6 +302,113 @@ function createRailsRouter() {
             resolvedProfile = undefined; // fall through to QueueManager default resolution
         }
         try {
+            // Loop mode: run a published loop (the Loops feature) against each spec,
+            // one app-driven LoopRun per ticket (mirrors ultracode's per-ticket model).
+            // Drives raw prompts via the LoopRunManager — NO queue job, NO slash command.
+            // rails-as-loops: a chosen loop (factory OR custom) runs through the
+            // LoopRunManager when Loops are enabled — so factory loops get their
+            // autonomous verify→fix loop too. (Loops off / no loopId → the legacy
+            // bare-mode QueueManager path below; `mode` is the derived factory mode.)
+            if ((0, feature_flags_1.isLoopsEnabled)() && typeof loopId === 'string' && loopId) {
+                let loopGraph;
+                let loopName;
+                if ((0, loop_factory_1.isFactoryLoopId)(loopId)) {
+                    const f = (0, loop_factory_1.getFactoryLoop)(loopId);
+                    if (!f) {
+                        res.status(404).json({ error: 'Factory loop not found' });
+                        return;
+                    }
+                    loopGraph = f.graph;
+                    loopName = f.name;
+                }
+                else {
+                    const loop = (0, loops_store_1.getLoop)(c.desktopDb, loopId);
+                    if (!loop) {
+                        res.status(404).json({ error: 'Loop not found' });
+                        return;
+                    }
+                    if (loop.status !== 'published') {
+                        res.status(400).json({ error: 'Loop must be published before it can run on a rail' });
+                        return;
+                    }
+                    loopGraph = loop.graph;
+                    loopName = loop.name;
+                }
+                let effort;
+                if (reasoning_effort !== undefined && reasoning_effort !== null) {
+                    if (typeof reasoning_effort !== 'string' || !VALID_REASONING_EFFORTS.has(reasoning_effort)) {
+                        res.status(400).json({ error: 'reasoning_effort must be one of: low, medium, high' });
+                        return;
+                    }
+                    effort = reasoning_effort;
+                }
+                const loopProvider = railProvider ?? c.project.provider ?? 'claude';
+                const loopModel = typeof model === 'string' && model ? model : (0, providers_1.getAdapter)(loopProvider).defaultModel();
+                // The loop's command(s) declare ticket scope + claude-only-ness.
+                const promptsText = loopGraph.nodes
+                    .filter((n) => n.type === 'ai-step')
+                    .map((n) => String(n.data?.prompt ?? ''))
+                    .join('\n');
+                if ((0, loop_command_catalog_1.referencesClaudeOnlyCommand)(promptsText) && loopProvider !== 'claude') {
+                    res.status(400).json({ error: 'This loop uses a Claude-only command and requires the Claude provider' });
+                    return;
+                }
+                const scope = (0, loop_command_catalog_1.dominantTicketScope)(promptsText);
+                // Spawn from the SAME cwd a rail uses (workspace when relocated, else the
+                // repo) so native `{{cmd:*}}` slash commands resolve — and surface the repo
+                // via SPECRAILS_REPO_DIR + `--add-dir` exactly like QueueManager.
+                const loopExec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: c.project.slug, path: c.project.path });
+                const loopRunIds = [];
+                const launchLoopRun = (runId, ticketIds, spec) => {
+                    c.railLoopRuns.set(runId, { railIndex, ticketIds });
+                    c.loopRunManager
+                        .run({
+                        runId,
+                        loopId,
+                        loopName,
+                        graph: loopGraph,
+                        projectId: c.project.id,
+                        cwd: loopExec.cwd,
+                        repoDir: loopExec.relocated ? loopExec.repoDir : undefined,
+                        railIndex,
+                        ticketId: ticketIds[0],
+                        spec: spec ? { ...spec, ticketIds } : { ticketIds },
+                        constants: (0, loop_constants_1.loadConstantMap)(c.desktopDb),
+                        provider: loopProvider,
+                        model: loopModel,
+                        effort,
+                    })
+                        .then((r) => c.onLoopRunFinished(r.runId, r.outcome))
+                        .catch((err) => {
+                        console.error('[rails-router] loop run failed:', err);
+                        c.onLoopRunFinished(runId, 'failed');
+                    });
+                    loopRunIds.push(runId);
+                    try {
+                        c.jiraSyncManager.onRailLaunch(ticketIds, runId);
+                    }
+                    catch { /* non-fatal */ }
+                };
+                if (scope === 'all') {
+                    // ONE run over ALL the rail's tickets ({{spec.ids}} = #1 #2 #3).
+                    const allIds = [...rail.ticketIds];
+                    launchLoopRun((0, ids_1.newId)(), allIds, c.getTicketSpec(allIds[0]));
+                }
+                else {
+                    // One run per ticket.
+                    for (const ticketId of rail.ticketIds) {
+                        launchLoopRun((0, ids_1.newId)(), [ticketId], c.getTicketSpec(ticketId));
+                    }
+                }
+                res.status(202).json({ loopRunIds, railIndex, mode });
+                return;
+            }
+            // A custom-loop launch (mode='loop') with no loopId is invalid — there is
+            // no factory loop to fall back to (only implement/batch/ultracode do).
+            if (mode === 'loop') {
+                res.status(400).json({ error: 'loopId is required for loop mode' });
+                return;
+            }
             let jobId;
             if (mode === 'ultracode') {
                 // Ultracode launches ONE independent Claude job per ticket — each gets
@@ -355,7 +502,10 @@ function createRailsRouter() {
         const targetJobIds = Array.from(c.railJobs.entries())
             .filter(([, meta]) => meta.railIndex === railIndex)
             .map(([jobId]) => jobId);
-        if (targetJobIds.length === 0) {
+        const targetLoopRunIds = Array.from(c.railLoopRuns.entries())
+            .filter(([, meta]) => meta.railIndex === railIndex)
+            .map(([runId]) => runId);
+        if (targetJobIds.length === 0 && targetLoopRunIds.length === 0) {
             res.status(404).json({ error: 'No active rail job found for this rail' });
             return;
         }
@@ -382,7 +532,26 @@ function createRailsRouter() {
             };
             c.broadcast(stopMsg);
         }
-        res.json({ ok: true, jobIds: targetJobIds, canceled: canceledCount });
+        // Loop runs (Loops mode): request cancellation. The engine settles 'stopped'
+        // at the next node boundary and onLoopRunFinished releases the rail's tickets
+        // (so we deliberately do NOT delete railLoopRuns here).
+        for (const runId of targetLoopRunIds) {
+            try {
+                c.loopRunManager.cancel(runId);
+                canceledCount++;
+            }
+            catch (err) {
+                console.warn(`[rails-router] stop: loop cancel(${runId}) failed: ${err.message}`);
+            }
+            const stopMsg = {
+                type: 'loop.run_stopped',
+                projectId: c.project.id,
+                loopRunId: runId,
+                railIndex,
+            };
+            c.broadcast(stopMsg);
+        }
+        res.json({ ok: true, jobIds: targetJobIds, loopRunIds: targetLoopRunIds, canceled: canceledCount });
     });
     return router;
 }