specrails-desktop 2.28.0 → 2.29.0

package/server/dist/headroom-manager.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HeadroomManager = void 0;
+exports.HeadroomManager = exports.HEADROOM_MANAGED_PYTHON_VERSION = void 0;
+exports.getHeadroomManagedInstallPlan = getHeadroomManagedInstallPlan;
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
@@ -12,11 +13,15 @@ const desktop_db_1 = require("./desktop-db");
 const headroom_routing_1 = require("./headroom-routing");
 const STATE_KEY = 'plugins.headroom.state';
 const DEFAULT_PORT = 8787;
+exports.HEADROOM_MANAGED_PYTHON_VERSION = '3.12';
 function nowIso() {
     return new Date().toISOString();
 }
+function specrailsHome() {
+    return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
+}
 function toolRoot() {
-    return path_1.default.join(os_1.default.homedir(), '.specrails', 'tools');
+    return path_1.default.join(specrailsHome(), '.specrails', 'tools');
 }
 function uvToolDir() {
     return path_1.default.join(toolRoot(), 'uv', 'tools');
@@ -24,6 +29,15 @@ function uvToolDir() {
 function uvCacheDir() {
     return path_1.default.join(toolRoot(), 'uv', 'cache');
 }
+function uvPythonInstallDir() {
+    return path_1.default.join(toolRoot(), 'uv', 'python');
+}
+function uvPythonCacheDir() {
+    return path_1.default.join(toolRoot(), 'uv', 'python-cache');
+}
+function uvPythonBinDir() {
+    return path_1.default.join(toolRoot(), 'uv', 'python-bin');
+}
 function uvBinDir() {
     return path_1.default.join(toolRoot(), 'bin');
 }
@@ -152,6 +166,40 @@ function classifyInstallFailure(output, command) {
     }
     return issue('unknown', output, command);
 }
+function getHeadroomManagedInstallPlan() {
+    return {
+        pythonVersion: exports.HEADROOM_MANAGED_PYTHON_VERSION,
+        pythonInstallArgs: [
+            'python',
+            'install',
+            exports.HEADROOM_MANAGED_PYTHON_VERSION,
+            '--managed-python',
+        ],
+        toolInstallArgs: [
+            'tool',
+            'install',
+            '--python',
+            exports.HEADROOM_MANAGED_PYTHON_VERSION,
+            '--managed-python',
+            '--force',
+            'headroom-ai[all]',
+        ],
+        env: {
+            UV_TOOL_DIR: uvToolDir(),
+            UV_TOOL_BIN_DIR: uvBinDir(),
+            UV_CACHE_DIR: uvCacheDir(),
+            UV_PYTHON: exports.HEADROOM_MANAGED_PYTHON_VERSION,
+            UV_MANAGED_PYTHON: 'true',
+            UV_PYTHON_DOWNLOADS: 'automatic',
+            UV_PYTHON_INSTALL_DIR: uvPythonInstallDir(),
+            UV_PYTHON_CACHE_DIR: uvPythonCacheDir(),
+            UV_PYTHON_BIN_DIR: uvPythonBinDir(),
+            UV_PYTHON_NO_REGISTRY: 'true',
+            UV_PYTHON_INSTALL_REGISTRY: 'false',
+            UV_NO_PROGRESS: '1',
+        },
+    };
+}
 function classifyProxyFailure(output, command) {
     const lower = output.toLowerCase();
     if (lower.includes('address already in use') ||
@@ -334,18 +382,32 @@ class HeadroomManager {
         fs_1.default.mkdirSync(uvToolDir(), { recursive: true });
         fs_1.default.mkdirSync(uvCacheDir(), { recursive: true });
         fs_1.default.mkdirSync(uvBinDir(), { recursive: true });
-        const args = ['tool', 'install', 'headroom-ai[all]', '--force'];
-        const command = `${uv} ${args.join(' ')}`;
-        const logs = [`Running ${command}`];
+        fs_1.default.mkdirSync(uvPythonInstallDir(), { recursive: true });
+        fs_1.default.mkdirSync(uvPythonCacheDir(), { recursive: true });
+        fs_1.default.mkdirSync(uvPythonBinDir(), { recursive: true });
+        const plan = getHeadroomManagedInstallPlan();
+        const pythonCommand = `${uv} ${plan.pythonInstallArgs.join(' ')}`;
+        const installCommand = `${uv} ${plan.toolInstallArgs.join(' ')}`;
+        const logs = [
+            `Ensuring Headroom Python runtime (CPython ${plan.pythonVersion})`,
+            `Running ${pythonCommand}`,
+        ];
         this.emit('installing', logs[0]);
-        const result = await this.runCommand(uv, args, {
-            UV_TOOL_DIR: uvToolDir(),
-            UV_TOOL_BIN_DIR: uvBinDir(),
-            UV_CACHE_DIR: uvCacheDir(),
-            UV_NO_PROGRESS: '1',
-        }, logs);
+        this.emit('installing', logs[1]);
+        const pythonResult = await this.runCommand(uv, plan.pythonInstallArgs, plan.env, logs);
+        if (pythonResult.code !== 0) {
+            const failure = classifyInstallFailure(logs.join('\n'), pythonCommand);
+            this.updatePersisted({ lastIssue: failure });
+            this.emit('failed', failure.title);
+            return { ok: false, state: this.getState(), issue: failure, logs };
+        }
+        logs.push(`Installing Headroom with managed CPython ${plan.pythonVersion}`);
+        logs.push(`Running ${installCommand}`);
+        this.emit('installing', logs[logs.length - 2]);
+        this.emit('installing', logs[logs.length - 1]);
+        const result = await this.runCommand(uv, plan.toolInstallArgs, plan.env, logs);
         if (result.code !== 0) {
-            const failure = classifyInstallFailure(logs.join('\n'), command);
+            const failure = classifyInstallFailure(logs.join('\n'), installCommand);
             this.updatePersisted({ lastIssue: failure });
             this.emit('failed', failure.title);
             return { ok: false, state: this.getState(), issue: failure, logs };
@@ -353,7 +415,7 @@ class HeadroomManager {
         const exe = this.resolveHeadroomInstall(null, false)?.path ?? null;
         const version = exe ? this.readHeadroomVersion(exe) : null;
         if (!exe || !version) {
-            const failure = issue('headroom_not_found_after_install', logs.join('\n'), command);
+            const failure = issue('headroom_not_found_after_install', logs.join('\n'), installCommand);
             this.updatePersisted({ lastIssue: failure });
             this.emit('failed', failure.title);
             return { ok: false, state: this.getState(), issue: failure, logs };
@@ -494,6 +556,9 @@ class HeadroomManager {
             toolDir: uvToolDir(),
             binDir: uvBinDir(),
             cacheDir: uvCacheDir(),
+            pythonInstallDir: uvPythonInstallDir(),
+            pythonBinDir: uvPythonBinDir(),
+            pythonCacheDir: uvPythonCacheDir(),
             proxyTail: this.proxyTail.slice(-4000),
             installSource: state.installSource,
             detectedRoutes: state.detectedRoutes,

package/server/dist/loop-factory.js

@@ -14,6 +14,13 @@ const GREEN_GOAL = 'Stop only when the latest verification step reports {{const:
 const FACTORY_MAX_ITERATIONS = 12;
 const FACTORY_LOOP_TIMEOUT_MIN = 360;
 const FACTORY_AI_STEP_TIMEOUT_MIN = 60;
+const SDD_QUICK_OPENSPEC_FACTORY = {
+    id: 'factory:sdd-quick-openspec',
+    name: 'SDD Quick (OpenSpec)',
+    description: 'Quick spec-driven OpenSpec lifecycle for small contract-governed changes: amend artifacts, apply, verify, and archive only after PASS.',
+    mode: 'loop',
+    graph: (0, loop_templates_1.opsxLifecycleGraph)(),
+};
 exports.FACTORY_LOOPS = [
     {
         id: 'factory:implement',
@@ -40,15 +47,15 @@ exports.FACTORY_LOOPS = [
         claudeOnly: true,
         graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:freestyle}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
     },
-    {
-        id: 'factory:openspec',
-        name: 'OpenSpec Lifecycle',
-        description: 'Ticket-to-archive OpenSpec lifecycle: generate artifacts (opsx:ff) → implement (opsx:apply) → verify (opsx:verify); on FAIL loop back and amend the same change, on PASS archive it unattended.',
-        mode: 'loop',
-        graph: (0, loop_templates_1.opsxLifecycleGraph)(),
-    },
+    SDD_QUICK_OPENSPEC_FACTORY,
 ];
-const FACTORY_BY_ID = new Map(exports.FACTORY_LOOPS.map((f) => [f.id, f]));
+const FACTORY_ALIASES = new Map([
+    ['factory:openspec', SDD_QUICK_OPENSPEC_FACTORY],
+]);
+const FACTORY_BY_ID = new Map([
+    ...exports.FACTORY_LOOPS.map((f) => [f.id, f]),
+    ...FACTORY_ALIASES,
+]);
 function getFactoryLoop(id) {
     return FACTORY_BY_ID.get(id);
 }

package/server/dist/loop-graph.js

@@ -155,6 +155,13 @@ function interpolateSpec(text, spec) {
             const ids = spec?.ticketIds ?? (spec?.id != null ? [spec.id] : []);
             return ids.map((id) => `#${id}`).join(' ');
         }
+        if (key === 'openspecChangeName') {
+            const direct = typeof spec?.openspecChangeName === 'string' ? spec.openspecChangeName.trim() : '';
+            const fromMetadata = typeof spec?.metadata?.openspecChangeName === 'string' ? spec.metadata.openspecChangeName.trim() : '';
+            return direct || fromMetadata;
+        }
+        if (!['id', 'title', 'description', 'status', 'priority', 'labels', 'jira_key', 'jira_url'].includes(key))
+            return '';
         const value = spec ? spec[key] : undefined;
         if (value == null)
             return '';

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

@@ -108,6 +108,7 @@ class LoopRunManager {
      *  id, which IS the backing job row's id — the manager-agnostic turn routing
      *  (project-router-jobs) addresses sessions by that job id. */
     _interactiveSteps = new Map();
+    _pausedHumanDecisions = new Map();
     constructor(db, broadcast, executors, now = () => Date.now()) {
         this.db = db;
         this.broadcast = broadcast;
@@ -122,6 +123,11 @@ class LoopRunManager {
      *  leave the engine's `await` hanging forever. */
     cancel(runId) {
         this._cancelled.add(runId);
+        const paused = this._pausedHumanDecisions.get(runId);
+        if (paused) {
+            this._pausedHumanDecisions.delete(runId);
+            paused.resolve({ action: 'stop' });
+        }
         const session = this._interactiveSteps.get(runId);
         if (session) {
             session.abort('■ Run canceled — tearing down the interactive step session.');
@@ -139,10 +145,23 @@ class LoopRunManager {
     isInteractiveJob(jobId) {
         return this._interactiveSteps.has(jobId);
     }
+    /** True while the loop is paused between engine steps awaiting a human call. */
+    isPaused(jobId) {
+        return this._pausedHumanDecisions.has(jobId);
+    }
+    pausedReason(jobId) {
+        return this._pausedHumanDecisions.get(jobId)?.reason ?? null;
+    }
     /** Feed one more user prompt to the ACTIVE step session owning this job row
      *  (queued behind the active turn — steering; the loop tends to continue its
      *  plan). Returns false when no interactive step is live for the id. */
     sendInteractiveTurn(jobId, text) {
+        const paused = this._pausedHumanDecisions.get(jobId);
+        if (paused) {
+            this._pausedHumanDecisions.delete(jobId);
+            paused.resolve({ action: 'resume', text });
+            return true;
+        }
         const session = this._interactiveSteps.get(jobId);
         if (!session)
             return false;
@@ -180,6 +199,14 @@ class LoopRunManager {
             }
         }
         this._activeChild.clear();
+        for (const [runId, paused] of this._pausedHumanDecisions.entries()) {
+            this._cancelled.add(runId);
+            try {
+                paused.resolve({ action: 'stop' });
+            }
+            catch { /* ignore */ }
+        }
+        this._pausedHumanDecisions.clear();
     }
     async run(req) {
         const runId = req.runId ?? (0, ids_1.newId)();
@@ -459,6 +486,65 @@ class LoopRunManager {
         // that loop-back so each iteration starts FRESH (re-reading the current code),
         // keeping context bounded regardless of pass count. Within an iteration the
         // steps still resume, so RED→GREEN→REFACTOR share context.
+        const awaitHumanDecision = async (reason) => {
+            const decisionPromise = new Promise((resolve) => {
+                this._pausedHumanDecisions.set(runId, { reason, resolve });
+            });
+            logLine(`\n■ Loop paused — needs a human decision: ${reason}`, 'stderr');
+            try {
+                (0, db_1.markJobInteractive)(this.db, runId);
+            }
+            catch { /* best-effort */ }
+            (0, loop_runs_store_1.pauseLoopRun)(this.db, runId, {
+                iterationCount: iteration,
+                totalCostUsd: totalCost,
+                totalTokens,
+                totalDurationMs: totalDuration,
+            });
+            const pausedAt = new Date(this.now()).toISOString();
+            this.broadcast({
+                type: 'loop.run_paused',
+                projectId: req.projectId,
+                loopRunId: runId,
+                railIndex: req.railIndex ?? null,
+                reason,
+                ticketIds: req.ticketId != null ? [req.ticketId] : [],
+            });
+            this.broadcast({
+                type: 'job.interactive',
+                projectId: req.projectId,
+                jobId: runId,
+                acceptingTurns: true,
+                settleMode: 'auto',
+                timestamp: pausedAt,
+            });
+            const decision = await decisionPromise;
+            if (decision.action === 'stop' || this._cancelled.has(runId)) {
+                logLine(`\n■ Loop stop requested while paused.`, 'stderr');
+                return { action: 'stop' };
+            }
+            (0, loop_runs_store_1.resumeLoopRun)(this.db, runId);
+            const answer = decision.text.trim();
+            const resumedAt = new Date(this.now()).toISOString();
+            logLine(`\n▶ Loop resumed — human decision received${answer ? `:\n${answer}` : '.'}`);
+            history.push(`Human decision: ${truncate(answer)}`);
+            this.broadcast({
+                type: 'loop.run_resumed',
+                projectId: req.projectId,
+                loopRunId: runId,
+                railIndex: req.railIndex ?? null,
+                ticketIds: req.ticketId != null ? [req.ticketId] : [],
+            });
+            this.broadcast({
+                type: 'job.interactive',
+                projectId: req.projectId,
+                jobId: runId,
+                acceptingTurns: false,
+                settleMode: 'auto',
+                timestamp: resumedAt,
+            });
+            return decision;
+        };
         const firstStepId = start ? req.graph.edges.find((e) => e.source === start.id)?.target : undefined;
         try {
             let nodeId = start?.id;
@@ -601,15 +687,20 @@ class LoopRunManager {
                         // Only carry forward the session of a step that actually ran — a
                         // hard-failed turn (codex still emits thread.started before its error)
                         // would otherwise make the next step `--resume` a dead session.
-                        if (res.sessionId && !stepFailed)
+                        if (res.sessionId && (!stepFailed || (blockedReason !== null && !res.failed && !zeroWork)))
                             aiSessionId = res.sessionId;
                         history.push(`AI Step: ${truncate(res.text)}`);
                         record(`loop:${runId}`, { ...res, failed: stepFailed }, aiStepStart);
                         if (blockedReason) {
-                            logLine(`\n■ Loop blocked — needs a human decision: ${blockedReason}`, 'stderr');
-                            outcome = 'blocked';
-                            settled = true;
-                            break;
+                            const decision = await awaitHumanDecision(blockedReason);
+                            if (decision.action === 'stop') {
+                                outcome = 'stopped';
+                                settled = true;
+                                break;
+                            }
+                            justContinued = true;
+                            nodeId = node.id;
+                            continue;
                         }
                         // Capture the OpenSpec change id from a step's output the FIRST time it
                         // appears (first-match-wins, kept stable across loop-back iterations so
@@ -754,10 +845,21 @@ class LoopRunManager {
                         // the fix for the verify→fix cycle spinning on an unanswered scope
                         // question the loop can't resolve on its own.
                         if (dec.blocked) {
-                            logLine(`\n■ Loop blocked — needs a human decision: ${dec.reasoning}`, 'stderr');
-                            outcome = 'blocked';
-                            settled = true;
-                            break;
+                            const decision = await awaitHumanDecision(dec.reasoning);
+                            if (decision.action === 'stop') {
+                                outcome = 'stopped';
+                                settled = true;
+                                break;
+                            }
+                            const target = branchTarget('continue') ?? conts[0]?.id ?? firstStepId;
+                            if (!target) {
+                                outcome = 'failed';
+                                settled = true;
+                                break;
+                            }
+                            justContinued = true;
+                            nodeId = target;
+                            continue;
                         }
                         // Non-convergence guard: if two consecutive 'continue' iterations
                         // leave the working tree byte-identical, the loop isn't progressing
@@ -846,11 +948,11 @@ class LoopRunManager {
         // 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).
-        // `blocked`/`stalled` are controlled halts (not done, not a hard crash) →
-        // surface as `canceled`, like a user stop, so tickets revert to todo rather
-        // than being marked done/on_review AND the run is never counted as success.
+        // `stopped`/`stalled` are controlled halts (not done, not a hard crash) →
+        // surface as `canceled`, so tickets revert to todo rather than being marked
+        // done/on_review AND the run is never counted as success.
         const jobStatus = outcome === 'success' ? 'completed'
-            : outcome === 'stopped' || outcome === 'blocked' || outcome === 'stalled' ? 'canceled'
+            : outcome === 'stopped' || outcome === 'stalled' ? 'canceled'
                 : 'failed';
         // `≥` when any cost-bearing step ended unpriced (timeout/crash) — the figure
         // is a lower bound, not exact.

package/server/dist/loop-runs-store.js

@@ -3,9 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLoopRun = createLoopRun;
 exports.updateLoopRunCounters = updateLoopRunCounters;
 exports.finishLoopRun = finishLoopRun;
+exports.pauseLoopRun = pauseLoopRun;
+exports.resumeLoopRun = resumeLoopRun;
 exports.getLoopRun = getLoopRun;
 exports.getRunEventCounts = getRunEventCounts;
 exports.listRunningLoopRuns = listRunningLoopRuns;
+exports.listActiveLoopRuns = listActiveLoopRuns;
 exports.listLoopRuns = listLoopRuns;
 exports.countRunningForLoop = countRunningForLoop;
 exports.reconcileOrphanLoopRuns = reconcileOrphanLoopRuns;
@@ -40,6 +43,16 @@ function finishLoopRun(db, id, opts) {
     db.prepare(`UPDATE loop_runs SET status = 'completed', final_outcome = ?, finished_at = ? WHERE id = ?`).run(opts.outcome, opts.finishedAt, id);
     return getLoopRun(db, id);
 }
+function pauseLoopRun(db, id, counters) {
+    if (counters)
+        updateLoopRunCounters(db, id, counters);
+    db.prepare(`UPDATE loop_runs SET status = 'paused' WHERE id = ? AND status = 'running'`).run(id);
+    return getLoopRun(db, id);
+}
+function resumeLoopRun(db, id) {
+    db.prepare(`UPDATE loop_runs SET status = 'running' WHERE id = ? AND status = 'paused'`).run(id);
+    return getLoopRun(db, id);
+}
 function getLoopRun(db, id) {
     return db.prepare('SELECT * FROM loop_runs WHERE id = ?').get(id);
 }
@@ -92,6 +105,11 @@ function listRunningLoopRuns(db, projectId) {
         .prepare("SELECT * FROM loop_runs WHERE project_id = ? AND status = 'running' ORDER BY started_at ASC")
         .all(projectId);
 }
+function listActiveLoopRuns(db, projectId) {
+    return db
+        .prepare("SELECT * FROM loop_runs WHERE project_id = ? AND status IN ('running','paused') ORDER BY started_at ASC")
+        .all(projectId);
+}
 function listLoopRuns(db, projectId, limit = 100) {
     return db
         .prepare('SELECT * FROM loop_runs WHERE project_id = ? ORDER BY started_at DESC LIMIT ?')
@@ -102,19 +120,20 @@ function listLoopRuns(db, projectId, limit = 100) {
  *  Running?" guard that blocks edit/delete of a loop while it executes. */
 function countRunningForLoop(db, loopId) {
     const row = db
-        .prepare(`SELECT COUNT(*) AS n FROM loop_runs WHERE loop_id = ? AND status = 'running'`)
+        .prepare(`SELECT COUNT(*) AS n FROM loop_runs WHERE loop_id = ? AND status IN ('running','paused')`)
         .get(loopId);
     return row.n;
 }
-/** Reconcile orphan runs at startup: any row still `status='running'` belongs to
- *  a process that is now dead (server restart, or a run killed before it could
- *  settle), so mark it terminal (`completed` + outcome `failed`). Without this an
- *  orphan keeps `countRunningForLoop > 0` forever, which wedges the loop as
- *  un-editable / un-publishable ("Failed to save loop" via the isRunning 409).
- *  Returns the number of rows reconciled. */
+/** Reconcile orphan runs at startup: any row still active belongs to a process
+ *  that is now dead (server restart, or a run killed before it could settle), so
+ *  mark it terminal (`completed` + outcome `failed`). A paused row is active too:
+ *  its resumable context lived in the old process. Without this an orphan keeps
+ *  `countRunningForLoop > 0` forever, which wedges the loop as un-editable /
+ *  un-publishable ("Failed to save loop" via the isRunning 409). Returns the
+ *  number of rows reconciled. */
 function reconcileOrphanLoopRuns(db, finishedAt) {
     const res = db
-        .prepare(`UPDATE loop_runs SET status = 'completed', final_outcome = COALESCE(final_outcome, 'failed'), finished_at = COALESCE(finished_at, ?) WHERE status = 'running'`)
+        .prepare(`UPDATE loop_runs SET status = 'completed', final_outcome = COALESCE(final_outcome, 'failed'), finished_at = COALESCE(finished_at, ?) WHERE status IN ('running','paused')`)
         .run(finishedAt);
     return res.changes ?? 0;
 }

package/server/dist/loop-templates.js

@@ -116,7 +116,11 @@ const OPSX_FF_PROMPT = [
     '',
     '{{spec.description}}',
     '',
-    'If a change id appears here — "{{run.changeId}}" — an OpenSpec change for this ticket already exists: CONTINUE that change (do NOT create a new one) and address only what the verification reported as still missing (see the context below). If it is blank, create the change and generate all required artifacts.',
+    'Structured OpenSpec target from the local ticket metadata: "{{spec.openspecChangeName}}". If this value is non-blank, CONTINUE that exact OpenSpec change and do NOT create a duplicate change for the same follow-up. If it is blank and no run change id exists, create a new OpenSpec change from this ticket and generate all required artifacts.',
+    '',
+    'If a run change id appears here — "{{run.changeId}}" — an OpenSpec change for this ticket already exists: CONTINUE that change (do NOT create a new one) and address only what the verification reported as still missing (see the context below).',
+    '',
+    'OpenSpec artifacts are authoritative. If the requested implementation changes requirements, acceptance criteria, design decisions, APIs, states, data models, or invariants, amend the relevant OpenSpec artifacts before any code changes.',
     '',
     'Run fully unattended: make reasonable decisions to keep momentum and NEVER stop to ask — there is no human to answer. When something is unclear, pick the most sensible option, proceed, and note the assumption.',
 ].join('\n');
@@ -125,6 +129,8 @@ const OPSX_APPLY_PROMPT = [
     '',
     'Implement every pending task of the active OpenSpec change for ticket "{{spec.title}}", editing code as needed and marking tasks complete as you finish them.',
     '',
+    'Before editing code, confirm the active OpenSpec artifacts already describe the contract being implemented. If implementation requires changing requirements, acceptance criteria, design decisions, APIs, states, data models, or invariants, stop code work and amend the OpenSpec artifacts first.',
+    '',
     'Run fully unattended: decide and keep momentum, never pause to ask. If you hit an ambiguity or blocker, make the most reasonable choice, implement it, and continue.',
 ].join('\n');
 const OPSX_VERIFY_PROMPT = [
@@ -132,9 +138,11 @@ const OPSX_VERIFY_PROMPT = [
     '',
     'Verify the active OpenSpec change against its specs, design, and tasks for ticket "{{spec.title}}". Be strict and honest — inspect the REAL code and tests, not any step\'s self-report.',
     '',
+    'Report FAIL if the implementation diverges from the active OpenSpec artifacts, or if code changed requirements, acceptance criteria, design decisions, APIs, states, data models, or invariants without corresponding artifact amendments.',
+    '',
     'Finish with a clear final line: exactly `{{const:VERIFICATION_PASS}}` when the change fully matches the ticket with nothing required missing, or `{{const:VERIFICATION_FAIL}} — <what is still missing>` otherwise.',
 ].join('\n');
-const OPSX_DECIDER_GOAL = 'The verify step reported {{const:VERIFICATION_PASS}} — the implementation fully matches ticket "{{spec.title}}" and nothing required is missing.';
+const OPSX_DECIDER_GOAL = 'The verify step reported {{const:VERIFICATION_PASS}} — the implementation fully matches the active OpenSpec artifacts for ticket "{{spec.title}}" and nothing required is missing.';
 /** The OpenSpec-lifecycle graph (see comment above). Exported for unit testing. */
 function opsxLifecycleGraph() {
     return {

package/server/dist/mcp/tools/jobs.js

@@ -38,9 +38,9 @@ function backgroundStartBusyReason(projectCtx) {
     if (activeJobId)
         return `job ${activeJobId} is still running`;
     try {
-        const runningLoops = (0, loop_runs_store_1.listRunningLoopRuns)(projectCtx.db, projectCtx.project.id);
-        if (runningLoops.length > 0)
-            return `loop run ${runningLoops[0].id} is still running`;
+        const activeLoops = (0, loop_runs_store_1.listActiveLoopRuns)(projectCtx.db, projectCtx.project.id);
+        if (activeLoops.length > 0)
+            return `loop run ${activeLoops[0].id} is still running`;
     }
     catch {
         // Some unit harnesses stub the DB narrowly; absence of loop metadata is not a blocker.

package/server/dist/mcp/tools/rails.js

@@ -52,6 +52,7 @@ function railsTools() {
                 'For on_review tickets with an already-open GitHub PR (including a published pr_ready delivery), launch automatically tries to continue that PR head branch; Jira-linked in_progress tickets can do the same when the PR match is explicit; fresh tickets still start from the project integration branch. ' +
                 'When launched from the in-app agent chat without an explicit aiEngine, the engine defaults to your conversation\'s provider (pass aiEngine to override; launch_all always uses each rail\'s stored engine). ' +
                 'User-facing naming: call the free-form autonomous mode "Freestyle"; use "freestyle" as the canonical API enum value for that same capability. ' +
+                'For small OpenSpec-governed work, recommend "SDD Quick (OpenSpec)" and launch with mode "loop" plus loopId "factory:sdd-quick-openspec"; keep Freestyle for ticket-local implementation-only work. ' +
                 'NAMING: railIndex is the 0-BASED internal identity; the dashboard shows rails 1-based ("Rail N" = railIndex N-1). When talking to the user, ALWAYS say "Rail <railIndex + 1>" (or the rail\'s custom name) — results include railLabel with the correct user-facing label.',
             hintTier: 'read',
             tier: (a) => {
@@ -114,7 +115,7 @@ function railsTools() {
                 loopId: zod_1.z
                     .string()
                     .optional()
-                    .describe('Loop id to run (launch). Factory ids (e.g. "factory:implement") map to a legacy mode; a custom published loop id keeps mode="loop". Browse/author loops with specrails_loops; the loop must be Published.'),
+                    .describe('Loop id to run (launch). Use "factory:sdd-quick-openspec" for SDD Quick (OpenSpec): small OpenSpec-governed work via mode="loop". Factory ids (e.g. "factory:implement") map to a legacy mode; a custom published loop id keeps mode="loop". Browse/author loops with specrails_loops; the loop must be Published.'),
                 reasoning_effort: zod_1.z
                     .enum(['low', 'medium', 'high'])
                     .optional()

package/server/dist/project-registry.js

@@ -712,6 +712,8 @@ class ProjectRegistry {
                     labels: t.labels,
                     jira_key: t.jira_key ?? null,
                     jira_url: t.jira_url ?? null,
+                    openspecChangeName: typeof t.metadata?.openspecChangeName === 'string' ? t.metadata.openspecChangeName : undefined,
+                    metadata: t.metadata,
                 };
             }
             catch {

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

@@ -23,9 +23,9 @@ function backgroundStartBusyReason(c) {
     if (activeJobId)
         return `job ${activeJobId} is still running`;
     try {
-        const runningLoops = (0, loop_runs_store_1.listRunningLoopRuns)(c.db, c.project.id);
-        if (runningLoops.length > 0)
-            return `loop run ${runningLoops[0].id} is still running`;
+        const activeLoops = (0, loop_runs_store_1.listActiveLoopRuns)(c.db, c.project.id);
+        if (activeLoops.length > 0)
+            return `loop run ${activeLoops[0].id} is still running`;
     }
     catch {
         // If the loop table is unavailable in a test harness, do not block startup.
@@ -249,7 +249,7 @@ function registerJobsRoutes(deps) {
                 // the loop is still executing — cancel through the engine instead of
                 // 404ing with a live child (the mission-modal "cancel did nothing" bug).
                 const loopRun = (0, loop_runs_store_1.getLoopRun)(c.db, id);
-                if (loopRun && loopRun.status === 'running' && c.loopRunManager) {
+                if (loopRun && (loopRun.status === 'running' || loopRun.status === 'paused') && c.loopRunManager) {
                     c.loopRunManager.cancel(id);
                     res.json({ ok: true, status: 'canceling' });
                     return;
@@ -280,7 +280,10 @@ function registerJobsRoutes(deps) {
     // 409 = neither manager has an active interactive session for the id
     // (unknown / non-interactive / finalized / between loop steps).
     router.post('/:projectId/jobs/:id/messages', (req, res) => {
-        if (!(0, feature_flags_1.isInteractiveJobsEnabled)()) {
+        const c = ctx(req);
+        const jobId = req.params.id;
+        const loopPaused = c.loopRunManager?.isPaused?.(jobId) ?? false;
+        if (!(0, feature_flags_1.isInteractiveJobsEnabled)() && !loopPaused) {
             res.status(403).json({ error: 'Interactive jobs are disabled on this server' });
             return;
         }
@@ -289,8 +292,6 @@ function registerJobsRoutes(deps) {
             res.status(400).json({ error: 'text is required' });
             return;
         }
-        const c = ctx(req);
-        const jobId = req.params.id;
         const accepted = c.queueManager.sendInteractiveTurn(jobId, text)
             || (c.loopRunManager?.sendInteractiveTurn(jobId, text) ?? false);
         if (!accepted) {
@@ -571,13 +572,16 @@ function registerJobsRoutes(deps) {
         // composer can phrase the waiting state truthfully instead of guessing.
         let interactiveSettleMode = null;
         let interactiveAcceptingTurns = false;
-        if ((0, feature_flags_1.isInteractiveJobsEnabled)() && job.interactive && job.status === 'running') {
+        const loopRun = (0, loop_runs_store_1.getLoopRun)(db, jobId);
+        const loopPaused = loopRun?.status === 'paused' || (c.loopRunManager?.isPaused?.(jobId) ?? false);
+        const loopPauseReason = c.loopRunManager?.pausedReason?.(jobId) ?? null;
+        if (job.status === 'running' && (((0, feature_flags_1.isInteractiveJobsEnabled)() && job.interactive) || loopPaused)) {
             const qmMode = queueManager.getInteractiveSettleMode?.(jobId) ?? null;
             const loopStepActive = c.loopRunManager?.isInteractiveJob?.(jobId) ?? false;
-            interactiveAcceptingTurns = qmMode !== null || loopStepActive;
-            interactiveSettleMode = qmMode ?? ((loopStepActive || (0, loop_runs_store_1.getLoopRun)(db, jobId)) ? 'auto' : null);
+            interactiveAcceptingTurns = qmMode !== null || loopStepActive || loopPaused;
+            interactiveSettleMode = qmMode ?? ((loopStepActive || loopPaused || loopRun) ? 'auto' : null);
         }
-        const annotated = { ...job, hasTelemetry: (0, db_1.hasJobTelemetry)(db, jobId), tickets, interactiveSettleMode, interactiveAcceptingTurns };
+        const annotated = { ...job, hasTelemetry: (0, db_1.hasJobTelemetry)(db, jobId), tickets, interactiveSettleMode, interactiveAcceptingTurns, loopPaused, loopPauseReason };
         res.json({ job: annotated, events, phaseDefinitions });
     });
     router.delete('/:projectId/jobs', (req, res) => {

package/server/dist/rails-router.js

@@ -111,7 +111,7 @@ function createRailsRouter() {
             // Also surface DB 'running' runs not tracked in-memory (the rail map is
             // cleared on every server restart) — DB is the authoritative source, so the
             // dashboard metrics survive both a page refresh AND a server restart.
-            for (const run of (0, loop_runs_store_1.listRunningLoopRuns)(c.db, c.project.id)) {
+            for (const run of (0, loop_runs_store_1.listActiveLoopRuns)(c.db, c.project.id)) {
                 if (run.rail_index == null || activeLoopRuns[run.rail_index])
                     continue;
                 const counts = (0, loop_runs_store_1.getRunEventCounts)(c.db, run.id);

package/server/dist/terminal-shell-integration.js

@@ -62,8 +62,11 @@ function warnShimMissingOnce(name) {
     _warnedShims.add(name);
     console.warn(`[terminal-shell-integration] bundled shim not found: ${name} — shell integration disabled for this shell`);
 }
+function specrailsHome() {
+    return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
+}
 function projectsRoot() {
-    return path_1.default.join(os_1.default.homedir(), '.specrails', 'projects');
+    return path_1.default.join(specrailsHome(), '.specrails', 'projects');
 }
 function shimDirFor(projectSlug, sessionId) {
     return path_1.default.join(projectsRoot(), projectSlug, 'terminals', sessionId);