specrails-desktop 2.62.0 → 2.63.1

package/docs/internals/safe-pr-review-flow.md

@@ -133,6 +133,21 @@ Both temporary checkouts use non-force cleanup, including after a Git runner exc
   including proofs for historical misplaced links; symlinked destination ancestors confer no
   authority. Registration paths, frozen manifests and Core scope remain unchanged. A failed run
   keeps its old checkout; after updating Desktop, a fresh Relaunch receives the corrected layout.
+- Warm reuse is gated by dependency freshness. Before preparing a new link for a package
+  directory, Desktop compares its dependency inputs in the base checkout and in the worktree: the
+  nearest lockfile found walking up to the Git top level (first of `pnpm-lock.yaml`, `yarn.lock`,
+  `package-lock.json`, `npm-shrinkwrap.json`, `bun.lock`, at the same relative position) and a
+  canonical digest of the `package.json` dependency, devDependency, optionalDependency and
+  peerDependency fields (scripts and other metadata are ignored). If either input differs, or one
+  cannot be read, the directory gets no `node_modules` and the run reports, on the
+  `rail.overlay_degraded` channel, for example
+  `apps/catalog: yarn.lock differs from the base checkout; dependencies will be installed in the worktree`.
+  Core's environment preparation then installs that directory cold from the worktree's own lockfile.
+  This prevents a base checkout on another branch, or behind the remote, from supplying packages
+  the run's code does not declare. Desktop never checks out, pulls or installs anything in the
+  user's checkout to make warm reuse possible. Links already present for a resumed run keep their
+  authentication; the guard only applies when a link is prepared. `SPECRAILS_WORKTREE_NODE_MODULES=false`
+  still disables warm reuse entirely.
 - Per-unit settlement returns structured execution + delivery results. `onLoopRunFinished` receives
   the engine outcome only; commit/status/ref/provenance/push failures cannot rewrite it.
 - Before staging, settlement blocks active OpenSpec change directories introduced relative to

package/docs/internals/source-map.md

@@ -5,7 +5,7 @@ architectural dependency declaration. Search a heading or filename and read only
 the relevant source and tests. Feature prefixes group the legacy server files;
 new bounded modules live under `server/modules/`.
 
-Includes 1042 source/build files. Nearby tests are linked where names
+Includes 1047 source/build files. Nearby tests are linked where names
 match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 ## cli
@@ -384,6 +384,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [LoopMigrationPanel.tsx](../../client/src/features/loops/components/LoopMigrationPanel.tsx) · [test](../../client/src/features/loops/components/__tests__/LoopMigrationPanel.test.tsx)
 - [LoopPreviewModal.tsx](../../client/src/features/loops/components/LoopPreviewModal.tsx)
 - [LoopRunModal.tsx](../../client/src/features/loops/components/LoopRunModal.tsx) · [test](../../client/src/features/loops/components/__tests__/LoopRunModal.test.tsx)
+- [LoopTurnLimits.tsx](../../client/src/features/loops/components/LoopTurnLimits.tsx) · [test](../../client/src/features/loops/components/LoopTurnLimits.test.tsx)
 - [LoopWindowSurface.tsx](../../client/src/features/loops/components/LoopWindowSurface.tsx) · [test](../../client/src/features/loops/components/__tests__/LoopWindowSurface.test.tsx)
 - [TemplatePreviewModal.tsx](../../client/src/features/loops/components/TemplatePreviewModal.tsx) · [test](../../client/src/features/loops/components/__tests__/TemplatePreviewModal.test.tsx)
 
@@ -413,6 +414,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [loop-export.ts](../../client/src/features/loops/lib/loop-export.ts) · [test](../../client/src/features/loops/lib/__tests__/loop-export.test.ts)
 - [loop-graph-rf.ts](../../client/src/features/loops/lib/loop-graph-rf.ts) · [test](../../client/src/features/loops/lib/__tests__/loop-graph-rf.test.ts)
 - [loop-layout.ts](../../client/src/features/loops/lib/loop-layout.ts) · [test](../../client/src/features/loops/lib/__tests__/loop-layout.test.ts)
+- [loop-role-agents.ts](../../client/src/features/loops/lib/loop-role-agents.ts)
 - [loop-run-models.ts](../../client/src/features/loops/lib/loop-run-models.ts) · [test](../../client/src/features/loops/lib/__tests__/loop-run-models.test.ts)
 - [loop-template-filter.ts](../../client/src/features/loops/lib/loop-template-filter.ts) · [test](../../client/src/features/loops/lib/__tests__/loop-template-filter.test.ts)
 - [loop-ticket-need.ts](../../client/src/features/loops/lib/loop-ticket-need.ts) · [test](../../client/src/features/loops/lib/__tests__/loop-ticket-need.test.ts)
@@ -848,7 +850,9 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [generate-icons.mjs](../../scripts/generate-icons.mjs)
 - [generate-mobile-types.mjs](../../scripts/generate-mobile-types.mjs)
 - [generate-source-map.mjs](../../scripts/generate-source-map.mjs) · [test](../../scripts/generate-source-map.test.mjs)
+- [module-references.mjs](../../scripts/module-references.mjs) · [test](../../scripts/module-references.test.mjs)
 - [obfuscate-chromium.mjs](../../scripts/obfuscate-chromium.mjs)
+- [paired-core-shards.mjs](../../scripts/paired-core-shards.mjs) · [test](../../scripts/paired-core-shards.test.mjs)
 - [patch-node-pty.mjs](../../scripts/patch-node-pty.mjs) · [test](../../scripts/patch-node-pty.test.mjs)
 - [recover-desktop-channel.mjs](../../scripts/recover-desktop-channel.mjs) · [test](../../scripts/recover-desktop-channel.test.mjs)
 - [release-policy.mjs](../../scripts/release-policy.mjs) · [test](../../scripts/release-policy.test.mjs)
@@ -1330,6 +1334,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [loop-shell-invocation.ts](../../server/modules/loops/runtime/loop-shell-invocation.ts)
 - [loop-step-idle.ts](../../server/modules/loops/runtime/loop-step-idle.ts) · [test](../../server/modules/loops/runtime/loop-step-idle.test.ts)
 - [loop-templates.ts](../../server/modules/loops/runtime/loop-templates.ts) · [test](../../server/modules/loops/runtime/loop-templates.test.ts)
+- [loop-turn-limits.ts](../../server/modules/loops/runtime/loop-turn-limits.ts) · [test](../../server/modules/loops/runtime/loop-turn-limits.test.ts)
 - [loops-router.ts](../../server/modules/loops/runtime/loops-router.ts) · [test](../../server/modules/loops/runtime/loops-router.test.ts)
 - [loops-store.ts](../../server/modules/loops/runtime/loops-store.ts) · [test](../../server/modules/loops/runtime/loops-store.test.ts)
 

package/docs/mcp.md

@@ -48,7 +48,7 @@ reading one description. The tools are:
 | `specrails_loops` | Saved loop workflows |
 | `specrails_code` | File discovery, literal content search, bounded line reads, summaries and provenance; AI summary regeneration is capability-gated |
 | `specrails_git` | Repository/branch/worktree information, status, diffs and PR lookup |
-| `specrails_env` | Project environment readiness and environment-file management |
+| `specrails_env` | Project environment readiness and environment-file management; `get`/`status`/`recheck` report each configured name's value-free resolution status |
 | `specrails_support` | Support triage, local diagnostics and specrails-core update workflows |
 | `specrails_setup` | Add-project setup wizard surface |
 | `specrails_analytics` | Per-project spending analytics + budget |

package/docs/platforms/macos.md

@@ -77,6 +77,8 @@ When the app runs without an active bundle (a runtimes-less build, or `npm run d
 
 2. **Login-shell merge (async)** — right after the HTTP server starts listening, `augmentPathFromLoginShell()` spawns `$SHELL -l -i` once (1500 ms timeout) and merges whatever `PATH` that login + interactive shell exposes. This recovers the segments that Volta, nvm, fnm, asdf, etc. add only inside your interactive shell — whatever your `$SHELL` produces, no specific rc file is assumed. On timeout or non-zero exit, the fast-path `PATH` stays in effect and a single warning is logged.
 
+Project environment names configured in Project Settings (for example `NODE_AUTH_TOKEN`) use a separate, per-project login-shell probe with a 10 s budget (`SPECRAILS_LOGIN_SHELL_TIMEOUT_MS`). It runs in the background, never writes to `process.env`, and reports a status per name. See [configuration](../internals/configuration.md#login-shell-recovery-and-resolution-status).
+
 The resolved `PATH` is stored on `process.env.PATH`, so every downstream spawn inherits it (`QueueManager` → provider CLI, `SetupManager` → `npx specrails-core`, `terminalManager` PTYs, etc.).
 
 ## Broken-symlink detection

package/docs/platforms/windows-parity.md

@@ -6,8 +6,8 @@ This audit covers the `codex/multi-repo-projects` branch, including mission stee
 
 | Feature | Windows implementation and checks |
 | --- | --- |
-| Installation, native runtimes | Native x64/ARM64 NSIS and MSI builds; embedded WebView2 offline provisioning; bundled Node/Git/core/OpenSpec; staged SQLite and full ConPTY/WinPTY dependency validation. |
-| Desktop updates | Installer-specific Tauri targets keep NSIS and MSI separate. Missing, empty or ambiguous artifact/signature pairs fail manifest generation. Generic NSIS entries remain for older clients. Publication is serialized, and previous download installers are retained until the remote manifest matches the new release. |
+| Installation, native runtimes | Native x64/ARM64 NSIS builds; WebView2 provisioning through the embedded bootstrapper; bundled Node/Git/core/OpenSpec; staged SQLite and full ConPTY/WinPTY dependency validation. |
+| Desktop updates | NSIS-specific and generic Tauri targets both reference the NSIS installer; earlier MSI installs fall back to the generic entry and the NSIS installer removes the WiX installation. Missing, empty or ambiguous artifact/signature pairs fail manifest generation. Publication is serialized, and previous download installers are retained until the remote manifest matches the new release. |
 | Startup and project catalog | Recover the actual Windows profile rather than inventing `C:\Users\Default`; SQLite catalog/repository IDs reopen under the same Unicode/spaced profile. |
 | Projects and multi-repo | Repository membership and canonical identity use real paths; junction and case aliases cannot add the same repository twice. Shared backlog and per-repository jobs retain their existing regression coverage. |
 | Core setup and updates | Offline assembly from the shipped core; preserve and restore the previous active framework if Windows junction replacement fails. Installed-package smoke waits for the real workspace marker. |
@@ -28,7 +28,7 @@ This audit covers the `codex/multi-repo-projects` branch, including mission stee
 
 `.github/workflows/windows-parity.yml` runs a `windows-parity` job on `windows-latest` (x64) for every pull request and push to `main`, adding `windows-11-arm` on the `main` pushes. It installs dependencies, checks TypeScript, runs release/PTY helper regression tests, native filesystem/process tests (retried once, they drive real processes), the application build, native host build/tests, and four real native fixtures: WebView2 capture/selection, authentication popups, mission window handoff, and browser multiwindow transfer/parking. It is deliberately a separate workflow from `ci.yml`: `release.yml` waits for CI only, so a slow or flaky Windows run never delays the release PR, while Desktop Release still builds and installs on Windows before publication. The jsdom client suite is not repeated on Windows; it runs on Linux in CI. The bundled-core matrix in `ci.yml` exercises Windows junction/copy relocation for providers.
 
-`.github/workflows/desktop-release.yml` builds the real installers and runs `scripts/smoke-windows-installers.ps1` before publishing artifacts. For each NSIS and MSI package, the script installs into a temporary path containing spaces and drives `scripts/smoke-installed-windows.mjs` with the installed Node runtime. The driver uses an isolated user profile and tests:
+`.github/workflows/desktop-release.yml` builds the real installers and runs `scripts/smoke-windows-installers.ps1` before publishing artifacts. The script fails on any MSI bundle, then installs the NSIS package into a temporary path containing spaces and drives `scripts/smoke-installed-windows.mjs` with the installed Node runtime. The driver uses an isolated user profile and tests:
 
 1. The installed pkg sidecar boots with bundled resources and authenticates API access.
 2. A temporary Git repository is registered and core assembly completes offline.
@@ -53,7 +53,7 @@ The detachable-window implementation has passed native macOS fixtures locally, i
 
 Before claiming complete Windows parity, record successful x64 and ARM64 CI/release runs and exercise the actual installed UI on supported Windows versions:
 
-- Clean NSIS and MSI installs, in-place upgrades from the previous release, relaunch, tray quit and uninstall. Verify one installation entry and preserved projects/logs.
+- Clean NSIS installs, in-place upgrades from the previous release (including an MSI-installed release migrating through the updater), relaunch, tray quit and uninstall. Verify one installation entry and preserved projects/logs.
 - Native browsing and capture at 100%, 150% and 200% display scaling; resize, maximize, multi-monitor movement, keyboard/clipboard, popup/self-close, and the relevant Okta/SSO tenant. Detach two active missions, minimize main independently, move them between monitors, and reattach into a window with its own open browser; verify both sessions and pending inputs remain intact.
 - Provider authentication and one real mission/rail per enabled provider; steering during a tool call; cancellation; multi-repo integration/checkout with clean and conflicting working trees.
 - Long-running frontend/backend processes, immediate startup failure, stopping nested processes, app quit/update during execution, and persisted logs after restart.

package/docs/platforms/windows.md

@@ -15,14 +15,14 @@ Installers are published on every release under:
 
 > 📥 `https://specrails.dev/downloads/specrails-desktop/latest/`
 
-Pick the pair that matches your CPU architecture:
+Pick the installer that matches your CPU architecture:
 
-| Architecture | NSIS installer (recommended) | MSI installer (enterprise/group-policy) |
-| --- | --- | --- |
-| x64 | `specrails-desktop-<version>-x64-setup.exe` | `specrails-desktop-<version>-x64.msi` |
-| ARM64 | `specrails-desktop-<version>-arm64-setup.exe` | `specrails-desktop-<version>-arm64.msi` |
+| Architecture | Installer |
+| --- | --- |
+| x64 | `specrails-desktop-<version>-x64-setup.exe` |
+| ARM64 | `specrails-desktop-<version>-arm64-setup.exe` |
 
-If you are unsure which to use, the NSIS `-setup.exe` is the right choice for individual installs; the MSI exists for enterprise deployment. Versioned copies live at `downloads/specrails-desktop/v<version>/` for archival and deep-linking.
+Windows ships only the NSIS installer. For unattended or managed deployment, run it silently with `/S` (optionally `/D=<install dir>` as the last argument). Releases up to 2.62 also published an `.msi`; see [Updates](#updates) for how those installations migrate. The installer provisions Microsoft Edge WebView2 when it is missing, downloading it through a small embedded bootstrapper (Windows 11 and current Windows 10 already include it). Versioned copies live at `downloads/specrails-desktop/v<version>/` for archival and deep-linking.
 
 A machine-readable `manifest.json` in `latest/` describes the current release (version, sha256, size) per platform, including `windows-x64` and `windows-arm64` entries — consumers can read it to build download links without hardcoding a version.
 
@@ -59,7 +59,7 @@ When the bundle is present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SP
 
 The desktop app self-updates via the Tauri updater plugin. It checks a GitHub Releases `latest.json` endpoint and, on Windows, applies updates with `installMode: "passive"` — the update runs with a minimal progress UI and the app relaunches into the new version.
 
-Updates preserve the installation format: NSIS installs receive a signed `-setup.exe` updater artifact, and MSI installs receive a signed `.msi` artifact for the same architecture. The signatures are Tauri/minisign integrity signatures, separate from Authenticode signing. An incomplete installer/signature pair blocks publication; the release no longer silently substitutes MSI for NSIS.
+Updates use the signed NSIS `-setup.exe` for the same architecture. Installations made from an earlier `.msi` receive that NSIS update too: the installer detects the MSI installation and removes it before installing, so a single installation remains (Windows may ask for administrator approval to remove the machine-wide MSI). The signatures are Tauri/minisign integrity signatures, separate from Authenticode signing. An incomplete installer/signature pair blocks publication.
 
 Normal quit and updates request an authenticated graceful shutdown of the owned sidecar first, giving processes and persistent logs time to close before a bounded force-stop fallback.
 
@@ -73,8 +73,8 @@ Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are pres
 
 ## Uninstall
 
-- NSIS: use the **Start Menu → Specrails → Uninstall** entry, or *Settings → Apps*.
-- MSI: use *Settings → Apps* or `msiexec /x <msi-path>`.
+- Use the **Start Menu → Specrails → Uninstall** entry, or *Settings → Apps*.
+- An installation from an earlier `.msi` release that has not updated yet: *Settings → Apps* or `msiexec /x <msi-path>`.
 
 ## Known limitations
 

package/local-runner/dist/specrails-local-runner.js

@@ -4036,7 +4036,7 @@ var require_core = __commonJS({
       constructor(opts = {}) {
         this.schemas = {};
         this.refs = {};
-        this.formats = {};
+        this.formats = /* @__PURE__ */ Object.create(null);
         this._compilations = /* @__PURE__ */ new Set();
         this._loading = {};
         this._cache = /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.62.0",
+  "version": "2.63.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -56,7 +56,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@tailwindcss/typography": "^0.5.19",
-    "ajv": "^8.17.1",
+    "ajv": "^8.20.0",
     "better-sqlite3": "^12.8.0",
     "chokidar": "^5.0.0",
     "cross-spawn": "^7.0.6",
@@ -71,29 +71,28 @@
     "selfsigned": "^5.5.0",
     "tree-kill": "^1.2.2",
     "werift": "^0.23.0",
-    "ws": "^8.21.0",
+    "ws": "^8.22.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@babel/parser": "^7.29.9",
     "@tauri-apps/cli": "^2.0.0",
     "@types/better-sqlite3": "^7.6.0",
-    "@types/chokidar": "^1.7.5",
     "@types/cross-spawn": "^6.0.6",
-    "@types/diff": "^7.0.2",
     "@types/express": "^5.0.6",
     "@types/js-yaml": "^4.0.9",
     "@types/multer": "^2.1.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^26.6.5",
     "@types/pdf-parse": "^1.1.5",
     "@types/supertest": "^7.2.0",
     "@types/ws": "^8.5.0",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^5.0.3",
     "concurrently": "^9.2.1",
     "esbuild": "^0.28.1",
     "supertest": "^7.2.2",
     "tsx": "^4.23.0",
-    "typescript": "^5.4.0",
-    "vitest": "^4.1.10"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "overrides": {
     "ip": "npm:@eggjs/ip@2.1.0",

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

@@ -15,6 +15,26 @@ function uniq(names) {
     }
     return out;
 }
+/** Names and states only: rebuild each record field by field so nothing but
+ *  the documented, value-free fields can ever reach an MCP client. */
+function sanitizeStatus(raw) {
+    const report = (raw && typeof raw === 'object' ? raw : {});
+    const names = Array.isArray(report.names) ? report.names : [];
+    return {
+        checking: report.checking === true,
+        loginShellRecovery: report.loginShellRecovery !== false,
+        timeoutMs: typeof report.timeoutMs === 'number' ? report.timeoutMs : null,
+        statuses: names
+            .filter((entry) => typeof entry?.name === 'string' && typeof entry?.status === 'string')
+            .map((entry) => ({
+            name: entry.name,
+            status: entry.status,
+            shell: typeof entry.shell === 'string' ? entry.shell : null,
+            checkedAt: typeof entry.checkedAt === 'string' ? entry.checkedAt : null,
+            exitCode: typeof entry.exitCode === 'number' ? entry.exitCode : null,
+        })),
+    };
+}
 function envTools() {
     return [
         {
@@ -22,11 +42,12 @@ function envTools() {
             title: 'Project worktree environment',
             description: 'Read, scan, and configure the per-project environment variable NAME allowlist used for rail jobs and isolated loop worktrees. ' +
                 'Values are never read or stored by this tool; runs read them from the server environment and can recover configured names from the login shell when the desktop process is missing them. scan inspects safe repo config files such as package.json, .npmrc, .yarnrc.yml and pnpm-workspace.yaml for ${VAR} / process.env.VAR references and private scoped package auth hints. ' +
-                'Actions: get (read current names), scan (discover candidates), set (write names), auto_configure (scan then merge discovered names into settings).',
+                'Each configured name reports a value-free resolution status: inherited, recovered (from the login shell), not-defined, probe-timeout or probe-failed. ' +
+                'Actions: get (read current names and their statuses), status (statuses only), recheck (probe the login shell now, then return statuses), scan (discover candidates), set (write names), auto_configure (scan then merge discovered names into settings).',
             hintTier: 'read',
             tier: (args) => (args.action === 'set' || args.action === 'auto_configure' ? 'write' : 'read'),
             inputSchema: {
-                action: zod_1.z.enum(['get', 'scan', 'set', 'auto_configure']).describe('Operation'),
+                action: zod_1.z.enum(['get', 'status', 'recheck', 'scan', 'set', 'auto_configure']).describe('Operation'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
                 names: zod_1.z.array(zod_1.z.string()).optional().describe('set: env var names to configure'),
                 merge: zod_1.z.boolean().optional().describe('set: merge with existing names instead of replacing them (default true)'),
@@ -36,7 +57,21 @@ function envTools() {
                 const base = (0, types_1.projectPath)(ctx, args.projectId);
                 if (action === 'get') {
                     const settings = await (0, types_1.apiCall)(ctx, 'GET', `${base}/settings`);
-                    return { names: Array.isArray(settings.worktreeEnvPassthrough) ? settings.worktreeEnvPassthrough : [] };
+                    const names = Array.isArray(settings.worktreeEnvPassthrough) ? settings.worktreeEnvPassthrough : [];
+                    // Statuses are best-effort: an older server without the route still answers names.
+                    try {
+                        const { statuses } = sanitizeStatus(await (0, types_1.apiCall)(ctx, 'GET', `${base}/env-passthrough/status`));
+                        return { names, statuses };
+                    }
+                    catch {
+                        return { names };
+                    }
+                }
+                if (action === 'status') {
+                    return sanitizeStatus(await (0, types_1.apiCall)(ctx, 'GET', `${base}/env-passthrough/status`));
+                }
+                if (action === 'recheck') {
+                    return sanitizeStatus(await (0, types_1.apiCall)(ctx, 'POST', `${base}/env-passthrough/recheck`));
                 }
                 if (action === 'scan') {
                     const project = (0, types_1.requireProject)(ctx, args.projectId).project;

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

@@ -30,7 +30,7 @@ function loopsTools() {
                 'For a standalone ticket-less run use the run action. ' +
                 'Actions: ' +
                 'list (all saved loops), ' +
-                'get (one loop by id), ' +
+                'get (one loop by id, plus turnLimits: each AI step\'s role and effective Maximum turns — set graph.config.agents.roles.<role>.maxTurns, or agents.<role> for built-in roles, then publish; project Agent Runtime settings never change loop runs), ' +
                 'templates (built-in template catalog with graphs), ' +
                 'factory (the built-in loops — factory:implement, factory:freestyle, factory:sdd-quick-openspec — with the graph a rail launch runs; ' +
                 'built-ins are ordinary editable loops whose loopId IS the factory id: change them with update + publish and the change applies to every rail, chat launch and companion that uses that built-in), ' +

package/server/dist/modules/agent-runtime/runtime/agent-runtime-bridge.js

@@ -23,6 +23,7 @@ const agent_runtime_package_1 = require("./agent-runtime-package");
 const agent_runtime_settings_1 = require("./agent-runtime-settings");
 const core_node_runtime_1 = require("../../../core-node-runtime");
 const win_spawn_1 = require("../../../util/win-spawn");
+const loop_turn_limits_1 = require("../../loops/runtime/loop-turn-limits");
 function runtimeChangeName(runId) {
     return 'runtime-' + (0, node_crypto_1.createHash)('sha256').update(runId).digest('hex').slice(0, 20);
 }
@@ -265,9 +266,17 @@ async function runAgentRuntimeInvocation(options) {
     }
     if ((0, node_fs_1.existsSync)(frozenPath)) {
         const frozen = JSON.parse((0, node_fs_1.readFileSync)(frozenPath, 'utf8'));
-        for (const [role, assignment] of [...Object.entries(frozen.agents), ...(frozen.fixer ? [['fixer', frozen.fixer]] : [])]) {
+        // A definition names the roles its steps run (Implement: plan/build/assess/correct); list exactly those with their turn ceiling.
+        const definitionRoles = definitionEngine ? JSON.parse((0, node_fs_1.readFileSync)(definitionFile, 'utf8')).roles : undefined;
+        const used = Array.isArray(definitionRoles) ? new Set(definitionRoles.filter((role) => typeof role === 'string')) : undefined;
+        if (used?.has('developer'))
+            used.add('fixer');
+        const assignments = [...Object.entries(frozen.agents), ...(frozen.fixer ? [['fixer', frozen.fixer]] : []), ...Object.entries(frozen.roles ?? {})]
+            .filter(([role]) => used ? used.has(role) : role in frozen.agents || role === 'fixer');
+        for (const [role, assignment] of assignments) {
+            const turns = assignment.maxTurns === undefined ? `max ${loop_turn_limits_1.CORE_DEFAULT_MAX_TURNS} turns (Core default)` : `max ${assignment.maxTurns} turns`;
             try {
-                options.onLine?.(`[runtime] ${role}: ${assignment.provider}/${assignment.model ?? 'provider default'}\n`);
+                options.onLine?.(`[runtime] ${role}: ${assignment.provider}/${assignment.model ?? 'provider default'} · ${turns}\n`);
             }
             catch { /* Log observers cannot prevent execution. */ }
         }
@@ -378,7 +387,8 @@ async function runAgentRuntimeInvocation(options) {
                 const kind = payload?.type === 'step_succeeded' && payload.outcome === 'fail' ? 'verification_failed' : payload?.type;
                 const completionDetail = payload?.type === 'workflow_failed' && Array.isArray(payload.reasons)
                     ? payload.reasons.filter(reason => typeof reason === 'string' && reason.trim()).join('; ').slice(0, 4_000) : undefined;
-                const detail = payload?.error?.message ?? payload?.message ?? completionDetail;
+                const rawDetail = payload?.error?.message ?? payload?.message ?? completionDetail;
+                const detail = payload?.type === 'step_failed' && typeof rawDetail === 'string' ? (0, loop_turn_limits_1.withTurnLimitHint)(rawDetail, payload.stepId) : rawDetail;
                 const stepKey = JSON.stringify([payload?.scopeId ?? null, payload?.nodePath ?? payload?.stepId ?? null]);
                 if (payload?.type === 'step_failed' && typeof detail === 'string' && detail.trim()) {
                     stepFailures.delete(stepKey);

package/server/dist/modules/delivery/runtime/rail-isolated-launch.js

@@ -447,7 +447,7 @@ function createIsolatedRunSettlement(ports) {
                 run: a, implementationOutcome, deliveryOutcome: 'blocked',
                 initialSha: a.initialSha, finalSha: await readHeadSha(git, a.handle.worktreePath),
                 failureCode: 'settlement_interrupted',
-                failureDetail: 'Programmatic workflow needs attention. Resume it from Agent Runtime settings in its original worktree.',
+                failureDetail: 'Programmatic workflow stopped before delivery; partial changes stay in its original worktree. The run log names the failing step. A resumable step offers Resume on the job page; a raised loop limit (such as a step\'s Maximum turns) needs a new launch.',
                 safeToRelease: false,
             };
         }

package/server/dist/modules/execution/runtime/queue-manager.js

@@ -2217,8 +2217,12 @@ class QueueManager {
         // values are read from the server env (with login-shell recovery for missing
         // names) at spawn time. Apply this before Specrails' own env overlays so
         // internal SPECRAILS_* control-plane values always win.
+        let environmentNotice = null;
         if (this._db) {
             spawnEnv = (0, project_env_1.applyWorktreeEnvPassthrough)(this._db, spawnEnv);
+            // One value-free line naming unresolved configured names (written to the
+            // job log once the readers exist). The run proceeds without them.
+            environmentNotice = (0, project_env_1.worktreeEnvPassthroughWarning)(this._db, spawnEnv);
         }
         const telemetryEnabled = !!(this._projectId && this._db && (0, db_1.getProjectSettings)(this._db).pipelineTelemetryEnabled);
         // Resolve the framework version ONCE at spawn time — `framework/current`
@@ -2605,6 +2609,10 @@ class QueueManager {
         const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
         const stderrReader = (0, readline_1.createInterface)({ input: child.stderr, crlfDelay: Infinity });
         this._jobReaders.set(jobId, { stdout: stdoutReader, stderr: stderrReader });
+        if (environmentNotice) {
+            persistEvent({ event_type: 'log', source: 'stderr', payload: JSON.stringify({ line: environmentNotice }) }, false);
+            emitLine('stderr', environmentNotice);
+        }
         stdoutReader.on('line', (line) => {
             if (this._disposed)
                 return;

package/server/dist/modules/loops/runtime/loop-executors.js

@@ -181,6 +181,7 @@ function createLoopExecutors(opts = {}) {
     const completionContexts = new Map();
     const runtimeConfigPath = (cwd) => (0, node_path_1.join)(opts.pluginScope?.().stateRoot ?? cwd, '.specrails', 'agent-runtime.json');
     return {
+        ...(opts.environmentNotice ? { environmentNotice: opts.environmentNotice } : {}),
         async cancelDefinition({ runId, contextPath, requestId }) {
             const host = (0, agent_runtime_bridge_1.readFrozenRuntimeHost)(contextPath, resolveEnv(), runId);
             await (0, agent_runtime_bridge_1.runAgentRuntimeControl)({ kind: 'cancel', runId, contextPath, requestId, ...host });

package/server/dist/modules/loops/runtime/loop-implement-recipe.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.supportsHostBlockers = exports.HOST_BLOCKER_KINDS = void 0;
+exports.supportsHostBlockers = exports.IMPLEMENT_WRITE_ROLE_MAX_TURNS = exports.HOST_BLOCKER_KINDS = void 0;
 exports.configurableImplementGraph = configurableImplementGraph;
 const agent_runtime_settings_1 = require("../../agent-runtime/runtime/agent-runtime-settings");
 const loop_agents_1 = require("./loop-agents");
@@ -12,6 +12,8 @@ const aspects = { type_correctness: 60, pattern_adherence: 60, test_coverage: 60
 const reviewPolicy = 'approved == true; issues must be empty; score >= 70; ' + Object.entries(aspects).map(([aspect, threshold]) => `${aspect} >= ${threshold}`).join('; ');
 exports.HOST_BLOCKER_KINDS = ['network', 'credential', 'environment-variable', 'toolchain', 'setup', 'environment', 'scope'];
 /** Fixer/developer structured `blocker`: the host ends the run on it instead of counting a correction round. */
+/** Write roles of a large spec routinely exceed Core's default of 100 turns (one cross-repo Developer used 113). */
+exports.IMPLEMENT_WRITE_ROLE_MAX_TURNS = 300;
 const blocker = objectSchema({ kind: { enum: [...exports.HOST_BLOCKER_KINDS] }, command: string, cwd: string, evidence: string, requiredAction: string }, ['kind', 'requiredAction']);
 /** Host-owned environment repair and structured blockers need the paired Core generation. */
 const supportsHostBlockers = (capabilities) => capabilities?.hostBlockers === 1;
@@ -24,9 +26,9 @@ function configurableImplementGraph(capabilities) {
     const agents = (0, loop_agents_1.defaultLoopAgents)();
     agents.roles = {
         plan: { ...agents.agents.architect, access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'architect') },
-        build: { ...agents.agents.developer, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'developer') },
+        build: { ...agents.agents.developer, maxTurns: exports.IMPLEMENT_WRITE_ROLE_MAX_TURNS, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'developer') },
         assess: { ...agents.agents.reviewer, access: 'read', artifacts: 'none', openspecSkill: 'openspec-verify-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'reviewer') },
-        correct: { ...agents.fixer, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'fixer') },
+        correct: { ...agents.fixer, maxTurns: exports.IMPLEMENT_WRITE_ROLE_MAX_TURNS, access: 'write', artifacts: 'tasks-checkboxes', openspecSkill: 'openspec-apply-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'fixer') },
     };
     const nodes = [{ id: 'start', type: 'start', position: { x: 0, y: 0 } }], edges = [];
     const node = (id, label, kind, params, outcomes) => {
@@ -48,7 +50,7 @@ function configurableImplementGraph(capabilities) {
     node('reset-confidence', 'Reset confidence after answer', 'assign', { set: { planInvestigated: false } }, { next: 'architect', failed: 'failed' });
     node('validate', 'Validate OpenSpec', 'openspec-validate', { change }, { pass: 'freeze', fail: 'architect', failed: 'failed' });
     node('freeze', 'Freeze approved artifacts', 'artifact-contract', { change, contractId: 'plan', action: 'freeze' }, { pass: 'initialize-corrections', fail: 'architect', failed: 'failed' });
-    node('initialize-corrections', 'Initialize automatic correction budget', 'assign', { set: { correctionAttempts: 0, correctionLimit: 3, implementationAttempts: 0, implementationLimit: 3 } }, { next: 'developer', failed: 'failed' });
+    node('initialize-corrections', 'Initialize automatic correction budget', 'assign', { set: { correctionAttempts: 0, correctionLimit: 3, implementationAttempts: 0, implementationLimit: 3, archiveRetries: 0 } }, { next: 'developer', failed: 'failed' });
     const implementation = objectSchema({ summary: string, incomplete: strings, blocker }, ['summary', 'incomplete']);
     turn('developer', 'Developer', 'build', `Implement every approved task for change ${change} using the bound official apply skill. Preserve proposal, design and specs; only tick tasks you completed. Report summary and incomplete task descriptions. If a task cannot be finished because of a host precondition or environment blocker outside this change (for example the sandbox forbids starting a local server, a credential or tool is missing), keep the work done, leave that task unchecked and return the structured blocker (kind, command, cwd, evidence, requiredAction). A failing test, a test you cannot make pass, or unexpected browser or tool behaviour is NOT a host blocker: change the test or the implementation instead. The host confirms a blocker by running its own verification before ending the run; a failure it reproduces comes back as a correction. Prior execution evidence and human answers: {{history.text}}`, implementation, 'developer-blocker', writes);
     node('developer-blocker', 'Developer reported a host blocker', 'condition', { expr: 'exists($outputs.developer.structured.blocker) && $outputs.developer.structured.blocker != null' }, { true: 'developer-blocker-kind', false: 'tasks' });
@@ -76,9 +78,14 @@ function configurableImplementGraph(capabilities) {
     node('correction-progress', 'Check correction progress', 'condition', { expr: 'exists($outputs.fixer.candidateHash) && $outputs.fixer.candidateHash != null && $outputs.fixer.candidateHash != $outputs.verify.candidateHash' }, { true: 'tasks', false: 'correction-stalled' });
     node('approve', 'Approve archive', 'approval', { reason: `Approve archiving the reviewed and verified candidate for change ${change}.`, bindCandidate: true, enabled: agents.approvalBeforeArchive === true }, { next: 'approval-policy' });
     node('approval-policy', 'Approval decision', 'condition', { expr: '$outputs.approve.response.approved == true' }, { true: 'archive', false: 'failed' });
-    node('archive', 'Archive OpenSpec', 'openspec-archive', { change, allowArchived: true, requiresVerified: true, reviewedCandidate: '{{outputs.reviewer.candidateHash}}', approvedCandidate: '{{outputs.approve.candidateHash}}' }, { next: 'verify-archive', failed: 'verify' });
+    node('archive', 'Archive OpenSpec', 'openspec-archive', { change, allowArchived: true, requiresVerified: true, reviewedCandidate: '{{outputs.reviewer.candidateHash}}', approvedCandidate: '{{outputs.approve.candidateHash}}' }, { next: 'verify-archive', failed: 'archive-retry' });
+    // Only a stale or unverified candidate is worth re-verifying before another archive attempt.
+    // An OpenSpec rejection (e.g. a requirement without SHALL/MUST) repeats identically, so it ends the run
+    // instead of cycling verify → review → archive until the transition budget runs out.
+    node('archive-retry', 'Archive needs a fresh verification', 'condition', { expr: 'exists($outputs.archive.reason) && ($outputs.archive.reason == "unverified" || $outputs.archive.reason == "candidate_changed") && $vars.archiveRetries < 2' }, { true: 'count-archive-retry', false: 'archive-failed' });
+    node('count-archive-retry', 'Count archive re-verification', 'assign', { increment: { archiveRetries: 1 } }, { next: 'verify', failed: 'failed' });
     node('verify-archive', 'Verify archived candidate', 'verify', verifyParams, verifyEnds('done', 'failed', 'host-blocked-archive'));
-    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 140 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 360, y: nodes.length * 140 }, data: { outcome: 'failure' } }, { id: 'correction-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction made no candidate changes. Host verification is valid: {{outputs.verify.valid}}. Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}` } }, { id: 'correction-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction limit reached ({{run.correctionAttempts}}/{{run.correctionLimit}}). Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}. Host verification: {{outputs.verify}}` } }, { id: 'implementation-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'The developer made no changes while approved tasks are still incomplete. Incomplete: {{outputs.developer.structured.incomplete}}. Developer summary: {{outputs.developer.structured.summary}}' } }, { id: 'implementation-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Implementation attempt limit reached ({{run.implementationAttempts}}/{{run.implementationLimit}}) with approved tasks still incomplete. Incomplete: {{outputs.developer.structured.incomplete}}. Developer summary: {{outputs.developer.structured.summary}}' } }, { id: 'developer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Developer reported a host blocker ({{outputs.developer.structured.blocker.kind}}): {{outputs.developer.structured.blocker.requiredAction}} Evidence: {{outputs.developer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'developer' } : {}) } }, { id: 'fixer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Fixer reported a host blocker ({{outputs.fixer.structured.blocker.kind}}): {{outputs.fixer.structured.blocker.requiredAction}} Evidence: {{outputs.fixer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'fixer' } : {}) } });
+    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 140 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 360, y: nodes.length * 140 }, data: { outcome: 'failure' } }, { id: 'archive-failed', type: 'end', position: { x: 360, y: (nodes.length + 1) * 140 }, data: { outcome: 'failure', reason: `OpenSpec could not archive change ${change}. The implementation was verified and reviewed; the archive step in the run log shows OpenSpec's reason (for example a requirement whose first body line has no SHALL or MUST). Fix the spec in the original worktree, then archive it there or relaunch.` } }, { id: 'correction-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction made no candidate changes. Host verification is valid: {{outputs.verify.valid}}. Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}` } }, { id: 'correction-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction limit reached ({{run.correctionAttempts}}/{{run.correctionLimit}}). Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}. Host verification: {{outputs.verify}}` } }, { id: 'implementation-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'The developer made no changes while approved tasks are still incomplete. Incomplete: {{outputs.developer.structured.incomplete}}. Developer summary: {{outputs.developer.structured.summary}}' } }, { id: 'implementation-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Implementation attempt limit reached ({{run.implementationAttempts}}/{{run.implementationLimit}}) with approved tasks still incomplete. Incomplete: {{outputs.developer.structured.incomplete}}. Developer summary: {{outputs.developer.structured.summary}}' } }, { id: 'developer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Developer reported a host blocker ({{outputs.developer.structured.blocker.kind}}): {{outputs.developer.structured.blocker.requiredAction}} Evidence: {{outputs.developer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'developer' } : {}) } }, { id: 'fixer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Fixer reported a host blocker ({{outputs.fixer.structured.blocker.kind}}): {{outputs.fixer.structured.blocker.requiredAction}} Evidence: {{outputs.fixer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'fixer' } : {}) } });
     if (hostBlockers) {
         const hostBlocked = (id, source) => ({ id, type: 'end', position: { x: 1800, y: nodes.length * 140 }, data: { outcome: 'failure', blockerFrom: source, reason: `Host blocker ({{outputs.${source}.blocker.kind}}): {{outputs.${source}.blocker.reason}} Required action: {{outputs.${source}.blocker.requiredAction}}` } });
         nodes.push(hostBlocked('host-blocked', 'verify'), hostBlocked('host-blocked-archive', 'verify-archive'));

package/server/dist/modules/loops/runtime/loop-run-manager.js

@@ -1009,6 +1009,13 @@ class LoopRunManager {
         logLine(`▶ Loop "${req.loopName ?? req.loopId}" started${req.spec?.title ? ` — spec: ${req.spec.title}` : ''}`);
         if (req.isolation)
             logLine(`⎇ Isolated worktree: ${req.isolation.worktreePath} (branch ${req.isolation.branch})`);
+        let environmentNotice = null;
+        try {
+            environmentNotice = this.executors.environmentNotice?.() ?? null;
+        }
+        catch { /* diagnostic only */ }
+        if (environmentNotice)
+            logLine(environmentNotice, 'stderr');
         if (!definitionEngine && !usageTelemetryAvailable) {
             logLine(`⚠️ ${adapter.displayName} does not report token/cost usage in headless mode; usage totals will remain unavailable.` +
                 (configuredMaxCostUsd !== undefined

package/server/dist/modules/loops/runtime/loop-turn-limits.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_DEFAULT_MAX_TURNS = void 0;
+exports.loopStepRole = loopStepRole;
+exports.loopTurnLimits = loopTurnLimits;
+exports.withTurnLimitHint = withTurnLimitHint;
+/** Core's ceiling for one role turn when the role sets no `maxTurns` (Core `cli-executor`). */
+exports.CORE_DEFAULT_MAX_TURNS = 100;
+function object(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** The agent role a canvas step runs, mirroring the definition compiler. */
+function loopStepRole(id, kind, params) {
+    if (kind === 'prompt')
+        return id === 'fix' ? 'fixer' : id === 'prepare' ? 'architect' : params.access === 'read' ? 'reviewer' : 'developer';
+    if ((kind === 'role-turn' || kind === 'decider') && typeof params.roleId === 'string')
+        return params.roleId;
+    if (kind === 'implementation-step' && ['architect', 'developer', 'reviewer', 'fixer'].includes(String(params.phase)))
+        return String(params.phase);
+    return undefined;
+}
+function roleEngine(agents, role) {
+    if (!agents)
+        return undefined;
+    if (role === 'fixer')
+        return agents.fixer ?? agents.agents.developer;
+    if (role === 'architect' || role === 'developer' || role === 'reviewer')
+        return agents.agents[role];
+    return agents.roles?.[role];
+}
+/** Effective per-step turn ceiling: step engine override, then the loop role, then Core's default. */
+function loopTurnLimits(graph) {
+    const agents = graph.config.agents;
+    const limits = [];
+    const visit = (body) => {
+        for (const node of body.nodes) {
+            if (node.type !== 'core')
+                continue;
+            const params = object(node.data?.params) ? node.data.params : {};
+            const role = loopStepRole(node.id, node.data?.kind, params);
+            if (!role)
+                continue;
+            const label = typeof node.data?.label === 'string' ? node.data.label : undefined;
+            const stepTurns = object(params.engine) ? params.engine.maxTurns : undefined;
+            const roleTurns = roleEngine(agents, role)?.maxTurns;
+            const [maxTurns, source] = typeof stepTurns === 'number' ? [stepTurns, 'step']
+                : typeof roleTurns === 'number' ? [roleTurns, 'role'] : [exports.CORE_DEFAULT_MAX_TURNS, 'core-default'];
+            limits.push({ stepId: node.id, ...(label ? { label } : {}), role, maxTurns, source });
+        }
+    };
+    visit(graph);
+    for (const component of Object.values(graph.components ?? {}))
+        visit(component);
+    return limits;
+}
+const TURN_LIMIT = /reached the configured limit of (\d+) turns for ([\w:-]+)/;
+/** Appends where to raise the limit to Core's turn-limit failure; other messages pass through. */
+function withTurnLimitHint(message, stepId) {
+    const match = message.match(TURN_LIMIT);
+    if (!match)
+        return message;
+    const step = stepId ? `the "${stepId}" step` : `the step that runs role "${match[2]}"`;
+    return `${message} To raise it: Loops ▸ this loop ▸ select ${step} ▸ "Maximum turns" (role "${match[2]}", currently ${match[1]}), save and publish. Project Settings do not change loop runs.`;
+}

package/server/dist/modules/loops/runtime/loops-router.js

@@ -17,6 +17,7 @@ const builtin_loops_1 = require("./builtin-loops");
 const loop_command_catalog_1 = require("./loop-command-catalog");
 const loop_constants_1 = require("./loop-constants");
 const loop_preview_1 = require("./loop-preview");
+const loop_turn_limits_1 = require("./loop-turn-limits");
 const BUILTIN_DELETE_MESSAGE = 'Built-in loops cannot be deleted. Use Restore original to reset it, or Duplicate it to keep a separate copy.';
 async function factoryCapabilities() {
     try {
@@ -281,7 +282,8 @@ function registerLoopsRoutes(router, deps) {
             res.status(404).json({ error: 'Loop not found' });
             return;
         }
-        res.json({ loop });
+        // Effective per-step turn ceilings, so readers (UI, MCP) never guess where the limit lives.
+        res.json({ loop, turnLimits: (0, loop_turn_limits_1.loopTurnLimits)(loop.graph) });
     });
     // ── Create ───────────────────────────────────────────────────────────────────
     router.post('/loops', (req, res) => {

package/server/dist/modules/missions/runtime/agent-operator-prompt.js

@@ -81,6 +81,14 @@ repository members, and runs coordinated AI coding pipelines over their selected
   (\`factory:implement\`, \`factory:freestyle\`, \`factory:sdd-quick-openspec\`)
   are editable in place: \`update\` + \`publish\` changes the built-in for every
   rail that uses it, \`restore_builtin\` resets it; \`duplicate\` makes a copy.
+  **Turn limits live in the loop, never in Settings.** Each AI step runs an
+  agent role with a "Maximum turns" ceiling (Core default 100 when unset).
+  \`specrails_loops(get)\` returns \`turnLimits\` (step → role → effective
+  value). Implement steps run roles plan/build/assess/correct (Architect,
+  Developer, Reviewer, Fixer), stored at \`graph.config.agents.roles.<role>.maxTurns\`.
+  To raise one: Loops ▸ the loop ▸ select the step ▸ "Maximum turns", save and
+  publish (or \`update\` + \`publish\`). Project Agent Runtime settings do not
+  change loop runs, and a failed run keeps its frozen limit: relaunch.
 - **Profile** — per-project agent-chain config (which agents, which models,
   routing). Supported by Claude and Kimi; forced to null on Codex/Gemini rails.
 - **Provider / engine** — claude, codex, gemini or kimi. A project installs one