specrails-desktop 2.34.1 → 2.35.0

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

@@ -292,14 +292,51 @@ function parseClaudeStreamLine(line) {
         const tool = blocks.find((b) => b.type === 'tool_use');
         if (tool?.name) {
             const input = JSON.stringify(parsed.message?.content?.[0]?.input ?? {});
-            return withAssistantUsage({ kind: 'tool-use', name: tool.name, inputPreview: input.slice(0, 200) }, msg);
+            return withAssistantUsage({
+                kind: 'tool-use',
+                name: tool.name,
+                inputPreview: input.slice(0, 200),
+                ...(typeof tool.id === 'string'
+                    ? { toolUseId: tool.id }
+                    : {}),
+            }, msg);
         }
         return withAssistantUsage({ kind: 'other', type, raw: parsed }, msg);
     }
     if (type === 'tool_use') {
         const name = parsed.name ?? '<unnamed>';
         const input = JSON.stringify(parsed.input ?? {});
-        return { kind: 'tool-use', name, inputPreview: input.slice(0, 200) };
+        return {
+            kind: 'tool-use',
+            name,
+            inputPreview: input.slice(0, 200),
+            ...(typeof parsed.id === 'string' ? { toolUseId: parsed.id } : {}),
+        };
+    }
+    // `user`-role frames carry tool RESULTS back to the model. Surface a bounded
+    // text projection so activity surfaces (agent chat's execution log) can show
+    // what a tool returned; frames without a tool_result block stay 'other'.
+    if (type === 'user') {
+        const msg = parsed.message;
+        const blocks = Array.isArray(msg?.content) ? msg.content : [];
+        const resultBlock = blocks.find((b) => b.type === 'tool_result');
+        if (resultBlock) {
+            const content = resultBlock.content;
+            const text = typeof content === 'string'
+                ? content
+                : Array.isArray(content)
+                    ? content
+                        .filter((c) => c.type === 'text' && typeof c.text === 'string')
+                        .map((c) => c.text)
+                        .join('\n')
+                    : '';
+            return {
+                kind: 'tool-result',
+                outputPreview: text.slice(0, 600),
+                ...(typeof resultBlock.tool_use_id === 'string' ? { toolUseId: resultBlock.tool_use_id } : {}),
+                ...(resultBlock.is_error === true ? { isError: true } : {}),
+            };
+        }
     }
     return { kind: 'other', type, raw: parsed };
 }

package/server/dist/queue-manager.js

@@ -26,6 +26,7 @@ const result_event_1 = require("./result-event");
 const crypto_1 = require("crypto");
 const providers_1 = require("./providers");
 const runtime_1 = require("./providers/runtime");
+const agent_defaults_1 = require("./agent-defaults");
 const codex_otel_bridge_1 = require("./codex-otel-bridge");
 const db_1 = require("./db");
 const interactive_job_session_1 = require("./interactive-job-session");
@@ -250,6 +251,7 @@ class QueueManager {
      *  For codex it controls the catalog model used at spawn time and as the
      *  fallback model name stamped onto the ai_invocations row. */
     _resolvedModel;
+    _agentDefaults;
     _onJobFinished;
     /** Project-owned durable effects that are part of every queue admission
      *  (for example, recovery/rail ownership). Invoked after queued_jobs has
@@ -356,6 +358,7 @@ class QueueManager {
         this._getDesktopDailyBudget = options?.getDesktopDailyBudget ?? null;
         this._adapter = (0, providers_1.getAdapter)(options?.provider ?? 'claude');
         this._resolvedModel = options?.resolvedModel ?? null;
+        this._agentDefaults = options?.agentDefaults ?? null;
         this._onJobFinished = options?.onJobFinished ?? null;
         this._onJobAdmission = options?.onJobAdmission ?? null;
         this._onBudgetExceeded = options?.onBudgetExceeded ?? null;
@@ -2272,9 +2275,22 @@ class QueueManager {
         // Per-job model override (consumed once) takes precedence — used by the
         // freestyle model picker so the user can choose haiku/sonnet/opus per launch.
         const modelOverride = this._jobModelSelection.get(jobId);
-        const fallbackRailModel = adapter.id === 'claude' && this._db
-            ? (0, db_1.getProjectSettings)(this._db).orchestratorModel
-            : (this._resolvedModel ?? adapter.defaultModel());
+        // Global Specrails Agents defaults (app Settings ▸ Specrails Agents) —
+        // read AT SPAWN TIME (no restart) and layered BELOW every project-level
+        // choice, ABOVE the built-in adapter default.
+        let globalAgentDefaults = null;
+        try {
+            globalAgentDefaults = this._agentDefaults?.(adapter.id) ?? null;
+        }
+        catch {
+            globalAgentDefaults = null;
+        }
+        const claudeProjectSettings = adapter.id === 'claude' && this._db ? (0, db_1.getProjectSettings)(this._db) : null;
+        const fallbackRailModel = claudeProjectSettings
+            ? (claudeProjectSettings.orchestratorModelExplicit
+                ? claudeProjectSettings.orchestratorModel
+                : globalAgentDefaults?.pipelineModel ?? claudeProjectSettings.orchestratorModel)
+            : (this._resolvedModel ?? globalAgentDefaults?.pipelineModel ?? adapter.defaultModel());
         // Relocate-artifacts: when relocated, claude is spawned from the workspace
         // so add `--add-dir <repoDir>` so its tools can still reach repo files by
         // absolute path. (gemini/codex get env-only tweaks at spawn time below.)
@@ -2301,7 +2317,24 @@ class QueueManager {
                 if (selection !== null && coreSupports) {
                     // selection is string (explicit) or undefined (default resolution)
                     const { resolveProfile, snapshotForJob, persistJobProfile, } = require('./profile-manager');
-                    const resolved = resolveProfile(execution.cwd, selection ?? undefined, adapter.id);
+                    let resolved = resolveProfile(execution.cwd, selection ?? undefined, adapter.id);
+                    // Global agent defaults: fill per-agent model gaps in the resolved
+                    // profile, or synthesize a baseline profile when the project has
+                    // none. Explicit profile choices always win; inert when the global
+                    // layer is off (byte-identical legacy behaviour).
+                    if (globalAgentDefaults && adapter.capabilities.profiles === true) {
+                        if (resolved) {
+                            const merged = (0, agent_defaults_1.mergeProfileWithAgentDefaults)(resolved.profile, globalAgentDefaults);
+                            if (merged.changed)
+                                resolved = { name: resolved.name, profile: merged.profile };
+                        }
+                        else if (Object.keys(globalAgentDefaults.agentModels).length > 0) {
+                            resolved = {
+                                name: agent_defaults_1.GLOBAL_DEFAULTS_PROFILE_NAME,
+                                profile: (0, agent_defaults_1.synthesizeProfileFromDefaults)(adapter, globalAgentDefaults),
+                            };
+                        }
+                    }
                     if (resolved) {
                         profileSnapshotPath = snapshotForJob(this._projectSlug, jobId, resolved);
                         profileName = resolved.name;
@@ -2322,10 +2355,19 @@ class QueueManager {
         // explicit per-job override > resolved profile orchestrator > project/default.
         // resolveProfile validates the profile model against this adapter's catalog.
         const railModel = modelOverride ?? profileOrchestratorModel ?? fallbackRailModel;
+        // Pipeline-level reasoning effort from the global layer (rails never had a
+        // per-job effort knob, so this is purely additive). Validated against the
+        // FINAL model — claude/codex sub-agents inherit the process-level effort,
+        // kimi rides its env knob via buildProviderEnv, gemini has no effort.
+        const globalRailEffort = globalAgentDefaults?.pipelineEffort
+            && (0, runtime_1.isReasoningEffortValidForModel)(adapter, railModel, globalAgentDefaults.pipelineEffort)
+            ? globalAgentDefaults.pipelineEffort
+            : undefined;
         const railSpawnOptions = {
             prompt: railPrompt,
             systemPrompt: systemAppend || undefined,
             model: railModel,
+            ...(globalRailEffort ? { reasoning_effort: globalRailEffort } : {}),
             extraArgs: railExtraArgs.length > 0 ? railExtraArgs : undefined,
         };
         const args = adapter.buildArgs('rail-job', railSpawnOptions);
@@ -2544,6 +2586,7 @@ class QueueManager {
                 // spawn and APPEND on top of the CLI default instead of replacing it.
                 systemPrompt: isFreestyle ? (systemAppend || undefined) : undefined,
                 model: railModel,
+                ...(globalRailEffort ? { reasoning_effort: globalRailEffort } : {}),
                 extraArgs: !isFreestyle && systemAppend
                     ? ['--append-system-prompt', systemAppend, ...(railExtraArgs ?? [])]
                     : (railExtraArgs.length > 0 ? railExtraArgs : undefined),

package/server/dist/rail-isolated-launch.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PrContinuationIsolationError = void 0;
+exports.buildSpecSnapshot = buildSpecSnapshot;
 exports.launchIsolatedRail = launchIsolatedRail;
 exports.reconcileRailWorktrees = reconcileRailWorktrees;
 /**
@@ -70,6 +71,7 @@ const rail_worktrees_store_1 = require("./rail-worktrees-store");
 const pr_naming_1 = require("./pr-naming");
 const jira_db_1 = require("./jira/jira-db");
 const db_1 = require("./db");
+const delivery_evidence_1 = require("./delivery-evidence");
 const integration_branch_1 = require("./integration-branch");
 const repo_lock_1 = require("./repo-lock");
 const rail_isolation_1 = require("./rail-isolation");
@@ -79,6 +81,7 @@ const rail_merge_orchestrator_1 = require("./rail-merge-orchestrator");
 const loop_executors_1 = require("./loop-executors");
 const worktree_overlay_1 = require("./worktree-overlay");
 const worktree_node_modules_1 = require("./worktree-node-modules");
+const revision_seed_1 = require("./revision-seed");
 const workspace_resolution_1 = require("./workspace-resolution");
 const feature_flags_1 = require("./feature-flags");
 const file_provenance_1 = require("./file-provenance");
@@ -125,6 +128,66 @@ function unitNamingInput(ctx, ticketId) {
     }
     return { ticketId, title: spec?.title ?? null, labels: spec?.labels ?? null, jiraKey };
 }
+/**
+ * Assemble the revision briefing from the generation being revised. Reads only
+ * durable rows, tolerates every one of them being absent (a legacy row carries
+ * no snapshot or evidence), and never throws — a thinner briefing is far better
+ * than a failed revision launch.
+ */
+function buildRevisionSeedForLaunch(db, revision, ticketIds) {
+    try {
+        const previous = (0, rail_pr_store_1.getPrDelivery)(db, revision.ofDeliveryId);
+        const branches = previous
+            ? [...new Set(JSON.parse(previous.branches || '[]').map((b) => b.branch).filter(Boolean))]
+            : [];
+        // Revision depth walks the supersession chain, bounded so a corrupted
+        // lineage can never spin here.
+        let depth = 1;
+        let cursor = previous;
+        for (let hops = 0; hops < 20 && cursor?.revision_of; hops++) {
+            depth += 1;
+            cursor = (0, rail_pr_store_1.getPrDelivery)(db, cursor.revision_of) ?? undefined;
+        }
+        return (0, revision_seed_1.buildRevisionSeed)({
+            note: revision.note,
+            specSnapshot: previous ? (0, rail_pr_store_1.readSpecSnapshot)(previous.spec_snapshot) : null,
+            ticketIds: [...ticketIds],
+            branches,
+            baseBranch: previous?.base_branch ?? 'the integration branch',
+            branchDiffSummary: null,
+            evidence: previous ? (0, delivery_evidence_1.readSettleEvidence)(previous.settle_evidence) : null,
+            revisionNumber: depth,
+        });
+    }
+    catch {
+        // Absolute floor: the user's instruction still reaches the run.
+        return revision.note;
+    }
+}
+/**
+ * Launch-time freeze of every covered ticket for the delivery row's
+ * spec_snapshot column (migration 56). The review packet's "what you asked"
+ * section renders this snapshot, never the live store — a spec edited mid-run
+ * must not rewrite what the delivery was asked to do. Failure-tolerant: an
+ * unreadable ticket degrades to a bare-id entry.
+ */
+function buildSpecSnapshot(ctx, ticketIds) {
+    return ticketIds.map((ticketId) => {
+        let spec;
+        try {
+            spec = ctx.getTicketSpec(ticketId);
+        }
+        catch {
+            /* tolerated — snapshot stays bare */
+        }
+        return {
+            ticketId,
+            title: spec?.title ?? null,
+            description: spec?.description ?? null,
+            labels: Array.isArray(spec?.labels) ? spec.labels : [],
+        };
+    });
+}
 /**
  * Commit messages are consumed by GitHub↔Jira development panels. Branch names
  * already carry the Jira key for new work; commits must too, especially when
@@ -323,7 +386,18 @@ async function launchIsolatedRail(input, io = {}) {
     const baseRepo = ctx.project.path;
     const slug = ctx.project.slug;
     const worktreesRoot = path.join((0, artifact_registry_1.resolveHome)(), '.specrails', 'projects', slug, 'worktrees');
-    const constants = (0, loop_constants_1.loadConstantMap)(ctx.desktopDb);
+    // A revision run is seeded with a full briefing (the instruction PLUS the
+    // frozen spec, the branch that carries the work and what the previous run
+    // actually reported) rather than the bare sentence — the run starts a FRESH
+    // provider session by contract, so durable context is the only thing it has.
+    // Per-RUN data, so it is layered over the project's constant map for this
+    // launch only and never persisted as a constant.
+    const constants = input.revision
+        ? {
+            ...(0, loop_constants_1.loadConstantMap)(ctx.desktopDb),
+            REVISION_REQUEST: buildRevisionSeedForLaunch(ctx.db, input.revision, ticketIds),
+        }
+        : (0, loop_constants_1.loadConstantMap)(ctx.desktopDb);
     // Capture the PR-delivery mode ONCE at launch entry so a mid-flight env flip
     // can never split one launch across the two delivery paths.
     const prMode = (0, rail_isolation_1.isRailPrDeliveryEnabled)();
@@ -582,9 +656,16 @@ async function launchIsolatedRail(input, io = {}) {
                     supersedesDeliveryId: launchContinuation?.source === 'rail-pr-delivery'
                         ? launchContinuation.deliveryId
                         : null,
+                    specSnapshot: buildSpecSnapshot(ctx, ticketIds),
+                    ...(input.revision ? { revisionNote: input.revision.note, revisionOf: input.revision.ofDeliveryId } : {}),
                 }, input.requiredPrContinuation
                     ? { id: input.requiredPrContinuation.deliveryId, decision: input.requiredPrContinuation.decision }
-                    : null);
+                    // A revision replaces the generation it revises, atomically, so the rail
+                    // never shows two active deliveries and a failed revision restores the
+                    // predecessor through the shipped rollback path.
+                    : input.revision
+                        ? { id: input.revision.ofDeliveryId, decision: input.revision.decision }
+                        : null);
                 prDeliveryId = generation.delivery.id;
                 supersededDelivery = generation.superseded;
                 input.onPrDeliveryCreated?.(prDeliveryId);
@@ -1362,7 +1443,25 @@ async function launchIsolatedRail(input, io = {}) {
             const expectedHeadByBranch = (0, rail_worktree_release_1.durableBranchHeads)(settledBranchRecords);
             const overlayEvidenceByBranch = (0, rail_worktree_release_1.durableOverlayCleanupEvidence)(settledBranchRecords);
             const settlementIgnoredByBranch = (0, rail_worktree_release_1.durableSettlementIgnoredPaths)(settledBranchRecords);
+            // Review-packet evidence harvest (deterministic, no model calls) — MUST
+            // run while the reviewable worktrees are still mounted, i.e. before the
+            // releaseRailWorktrees calls below. harvestDeliveryEvidence never throws
+            // by contract; the belt-and-braces catch keeps settle unconditional.
+            const harvest = io.harvestEvidence ?? delivery_evidence_1.harvestDeliveryEvidence;
+            let settleEvidence;
+            try {
+                settleEvidence = harvest({ readEvents: (runId) => (0, db_1.getJobEvents)(ctx.db, runId) }, results.map((result) => ({
+                    ticketId: result.run.ticketId,
+                    runId: result.run.runId,
+                    worktreePath: result.run.handle.worktreePath,
+                })));
+            }
+            catch (e) {
+                console.warn(`[rail-isolated] evidence harvest failed: ${e instanceof Error ? e.message : String(e)}`);
+                settleEvidence = undefined;
+            }
             const patch = {
+                settleEvidence,
                 branches: settledBranchRecords,
                 worktreeIds,
                 implementationOutcome,

package/server/dist/rail-pr-store.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PrDeliveryGenerationConflict = exports.ACTIVE_PR_DECISIONS = exports.TERMINAL_PR_DECISIONS = void 0;
+exports.PrDeliveryGenerationConflict = exports.ACTIVE_PR_DECISIONS = exports.TERMINAL_PR_DECISIONS = exports.REVISION_NOTE_CAP = void 0;
+exports.boundSpecSnapshot = boundSpecSnapshot;
+exports.boundRevisionNote = boundRevisionNote;
+exports.readSpecSnapshot = readSpecSnapshot;
 exports.isTerminalPrDecision = isTerminalPrDecision;
 exports.createPrDelivery = createPrDelivery;
 exports.createPrDeliveryGeneration = createPrDeliveryGeneration;
@@ -26,6 +29,34 @@ exports.toPrDeliverySnapshot = toPrDeliverySnapshot;
 exports.toRailPrStateMessage = toRailPrStateMessage;
 exports.toPrDecisionCardEnvelope = toPrDecisionCardEnvelope;
 const ids_1 = require("./ids");
+/** Defensive per-ticket cap; contract-layer specs run long but bounded. */
+const SPEC_SNAPSHOT_DESCRIPTION_CAP = 32_768;
+function boundSpecSnapshot(entries) {
+    return entries.map((entry) => ({
+        ticketId: entry.ticketId,
+        title: entry.title,
+        description: entry.description == null ? null : entry.description.slice(0, SPEC_SNAPSHOT_DESCRIPTION_CAP),
+        labels: entry.labels.slice(0, 32),
+    }));
+}
+/** A revision instruction is one sentence of intent, not a document. Bound it so
+ *  a pasted essay cannot bloat every snapshot that carries the row. */
+exports.REVISION_NOTE_CAP = 2000;
+function boundRevisionNote(note) {
+    return note.replace(/[\r\n\t\0]+/g, ' ').replace(/\s{2,}/g, ' ').trim().slice(0, exports.REVISION_NOTE_CAP);
+}
+/** Parse a persisted spec_snapshot column value (null-tolerant). */
+function readSpecSnapshot(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** States after which the delivery is closed (no further decision possible). */
 exports.TERMINAL_PR_DECISIONS = new Set(['completed', 'merged', 'discarded', 'superseded']);
 /** States in which the delivery still awaits (or is executing) a user decision. */
@@ -53,9 +84,12 @@ function createPrDelivery(db, input) {
        id, rail_index, loop_id, rail_key, ticket_ids, base_branch,
        loop_name, origin_surface, origin_conversation_id,
        implementation_outcome, delivery_outcome, status_code,
-       is_continuation, supersedes_delivery_id
+       is_continuation, supersedes_delivery_id, spec_snapshot,
+       revision_note, revision_of
      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', 'pending',
-       'implementation_running', ?, ?)`).run(id, input.railIndex, input.loopId ?? null, input.railKey, JSON.stringify(input.ticketIds), input.baseBranch, input.loopName, input.originSurface, input.originConversationId ?? null, input.isContinuation ? 1 : 0, input.supersedesDeliveryId ?? null);
+       'implementation_running', ?, ?, ?, ?, ?)`).run(id, input.railIndex, input.loopId ?? null, input.railKey, JSON.stringify(input.ticketIds), input.baseBranch, input.loopName, input.originSurface, input.originConversationId ?? null, input.isContinuation ? 1 : 0, input.supersedesDeliveryId ?? null, input.specSnapshot && input.specSnapshot.length > 0
+        ? JSON.stringify(boundSpecSnapshot(input.specSnapshot))
+        : null, input.revisionNote ? boundRevisionNote(input.revisionNote) : null, input.revisionOf ?? null);
     return getPrDelivery(db, id);
 }
 class PrDeliveryGenerationConflict extends Error {
@@ -345,6 +379,7 @@ const PATCH_COLUMNS = {
     operationStartedAtMs: 'operation_started_at_ms',
     cleanupWarnings: 'cleanup_warnings',
     safetyArchives: 'safety_archives',
+    settleEvidence: 'settle_evidence',
 };
 function patchValue(key, patch) {
     const raw = patch[key];
@@ -358,6 +393,8 @@ function patchValue(key, patch) {
         return raw == null ? null : boundPrDiagnostic(String(raw));
     if (key === 'isContinuation')
         return raw ? 1 : 0;
+    if (key === 'settleEvidence')
+        return raw == null ? null : JSON.stringify(raw);
     return raw;
 }
 /** Bounded, single-line diagnostics are safe to persist/broadcast as secondary

package/server/dist/rails-router.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.prDeliveryRevisionAllowed = prDeliveryRevisionAllowed;
 exports.createRailsRouter = createRailsRouter;
 const express_1 = require("express");
 const rails_store_1 = require("./rails-store");
@@ -11,6 +12,8 @@ const file_story_1 = require("./file-story");
 const loops_store_1 = require("./loops-store");
 const loop_runs_store_1 = require("./loop-runs-store");
 const providers_1 = require("./providers");
+const runtime_1 = require("./providers/runtime");
+const agent_defaults_1 = require("./agent-defaults");
 const spec_models_1 = require("./spec-models");
 const workspace_resolution_1 = require("./workspace-resolution");
 const loop_factory_1 = require("./loop-factory");
@@ -20,6 +23,8 @@ const loop_graph_1 = require("./loop-graph");
 const rail_isolation_1 = require("./rail-isolation");
 const rail_pr_store_1 = require("./rail-pr-store");
 const loop_effect_1 = require("./loop-effect");
+const review_packet_1 = require("./review-packet");
+const accept_ladder_1 = require("./accept-ladder");
 const rail_pr_decision_1 = require("./rail-pr-decision");
 const active_pr_continuation_1 = require("./active-pr-continuation");
 const rail_isolated_launch_1 = require("./rail-isolated-launch");
@@ -41,6 +46,22 @@ function prDeliveryContinuesTickets(delivery, ticketIds) {
     const requested = new Set(ticketIds);
     return requested.size > 0 && requested.size === covered.size && [...requested].every((id) => covered.has(id));
 }
+/**
+ * Whether a launch may revise an undecided delivery. Deliberately strict:
+ * the named id must BE the rail's active generation, that generation must still
+ * be awaiting a decision (a terminal one is history, not revisable), and the
+ * rail must still carry exactly the delivery's ticket set — a subset would
+ * revise work the user never asked about while leaving the rest undecided.
+ */
+function prDeliveryRevisionAllowed(delivery, revisionOfDeliveryId, ticketIds) {
+    if (delivery.id !== revisionOfDeliveryId)
+        return false;
+    if ((0, rail_pr_store_1.isTerminalPrDecision)(delivery.decision))
+        return false;
+    const covered = new Set(delivery.ticketIds);
+    const requested = new Set(ticketIds);
+    return requested.size > 0 && requested.size === covered.size && [...requested].every((id) => covered.has(id));
+}
 function prDeliveryCheckoutBlock(delivery) {
     if (delivery.deliveryOutcome === 'blocked') {
         return 'delivery is blocked and has no safely checkoutable result';
@@ -381,7 +402,20 @@ function createRailsRouter() {
             return;
         }
         let { mode = 'implement' } = req.body ?? {};
-        const { profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface, targetPrNumber } = req.body ?? {};
+        const { profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface, targetPrNumber, revisionOfDeliveryId, revisionNote } = req.body ?? {};
+        // Revision launch (nontech-review-experience Wave 3): the user asked for a
+        // change to a delivery that is already awaiting their decision. Shape is
+        // validated here; the narrow guard exemption is enforced below.
+        if (revisionOfDeliveryId !== undefined && revisionOfDeliveryId !== null) {
+            if (typeof revisionOfDeliveryId !== 'string' || !/^[A-Za-z0-9-]{1,64}$/.test(revisionOfDeliveryId)) {
+                res.status(400).json({ error: 'invalid_revision_target', detail: 'revisionOfDeliveryId must be a delivery id' });
+                return;
+            }
+            if (typeof revisionNote !== 'string' || revisionNote.trim().length === 0) {
+                res.status(400).json({ error: 'revision_note_required', detail: 'revisionNote must describe the change to make' });
+                return;
+            }
+        }
         // Explicit target PR (deliver-rail-into-existing-pr): the user names an
         // existing open PR as the delivery destination. Shape-validated here;
         // resolved and verified inside the isolated launch, fail-closed.
@@ -414,6 +448,18 @@ function createRailsRouter() {
                 res.status(404).json({ error: 'Factory loop not found' });
                 return;
             }
+            // The revision loop is meaningless without a revision to apply: its prompt
+            // consumes {{const:REVISION_REQUEST}}, and an unresolved constant renders
+            // as an EMPTY string (loop-constants), so naming it directly would spawn a
+            // run whose central instruction is silently blank. It is reachable by id
+            // (fork/preview resolve it), so the launch door has to refuse it.
+            if (loopId === loop_factory_1.FACTORY_REVISION_LOOP_ID && !revisionOfDeliveryId) {
+                res.status(400).json({
+                    error: 'revision_loop_requires_revision',
+                    detail: 'factory:revision only runs as a revision — pass revisionOfDeliveryId and revisionNote instead of naming the loop',
+                });
+                return;
+            }
             mode = fmode;
         }
         if (!VALID_MODES.has(mode)) {
@@ -429,6 +475,17 @@ function createRailsRouter() {
         if ((0, feature_flags_1.isLoopsEnabled)() && (typeof loopId !== 'string' || !loopId) && mode !== 'loop') {
             loopId = (0, loop_factory_1.factoryLoopForMode)(mode)?.id;
         }
+        // A revision must run the Architect-LESS revision loop, whatever the rail's
+        // stored mode is. Without this every one-sentence tweak would re-run the
+        // full implement pipeline — the exact cost the feature exists to avoid.
+        // An explicit loopId is respected (a caller naming a loop means it).
+        if (revisionOfDeliveryId && (0, feature_flags_1.isLoopsEnabled)() && (typeof loopId !== 'string' || !loopId || (0, loop_factory_1.isFactoryLoopId)(loopId))) {
+            const revisionLoop = (0, loop_factory_1.getFactoryLoop)(loop_factory_1.FACTORY_REVISION_LOOP_ID);
+            if (revisionLoop) {
+                loopId = revisionLoop.id;
+                mode = revisionLoop.mode;
+            }
+        }
         if (mode === 'loop' && !(0, feature_flags_1.isLoopsEnabled)()) {
             res.status(403).json({ error: 'Loops are disabled on this server' });
             return;
@@ -599,7 +656,14 @@ function createRailsRouter() {
                     res.status(400).json({ error: `model is not valid for provider "${loopProvider}"`, allowed: (0, spec_models_1.getModelsForProvider)(loopProvider) });
                     return;
                 }
-                const loopModel = typeof model === 'string' && model ? model : loopAdapter.defaultModel();
+                // Global Specrails Agents defaults (Settings ▸ Specrails Agents): fill
+                // model/effort ONLY when the launch body carries no explicit choice —
+                // dashboard factory launches send neither. Read at launch time, so a
+                // settings change applies to the next launch without restart.
+                const globalAgentDefaults = (0, agent_defaults_1.resolveAgentDefaults)(c.desktopDb, loopProvider);
+                const loopModel = typeof model === 'string' && model
+                    ? model
+                    : (globalAgentDefaults?.pipelineModel ?? loopAdapter.defaultModel());
                 let effort;
                 if (reasoning_effort !== undefined && reasoning_effort !== null) {
                     const allowed = (0, providers_1.reasoningEffortsForModel)(loopAdapter, loopModel);
@@ -613,6 +677,10 @@ function createRailsRouter() {
                     }
                     effort = reasoning_effort;
                 }
+                else if (globalAgentDefaults?.pipelineEffort
+                    && (0, runtime_1.isReasoningEffortValidForModel)(loopAdapter, loopModel, globalAgentDefaults.pipelineEffort)) {
+                    effort = globalAgentDefaults.pipelineEffort;
+                }
                 // The loop's command(s) declare ticket scope + required capabilities.
                 const promptsText = loopGraph.nodes
                     .filter((n) => n.type === 'ai-step')
@@ -634,6 +702,7 @@ function createRailsRouter() {
                 // cards) is diagnosable from the UI, not just the server log.
                 let isolationUnavailableDetail;
                 let continuablePrDelivery = null;
+                let revisionRequest = null;
                 // Read-only vs mutating is DERIVED from the loop's nodes (see loop-effect),
                 // not a user flag — a content-read-only loop (no ai-step/shell) never writes,
                 // so it is not isolated; anything that can write is.
@@ -644,10 +713,32 @@ function createRailsRouter() {
                 if ((0, rail_isolation_1.isRailPrDeliveryEnabled)()) {
                     const pending = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex);
                     const pendingSnapshot = pending ? (0, rail_pr_store_1.toPrDeliverySnapshot)(pending) : null;
-                    if (pendingSnapshot && !prDeliveryContinuesTickets(pendingSnapshot, rail.ticketIds)) {
+                    // A revision is the ONE launch allowed to proceed against an
+                    // undecided delivery, and only on the exact terms below: the caller
+                    // names that delivery AND covers its full ticket set. Anything else
+                    // would silently append work to branches the user has not judged.
+                    const revisionsEnabled = (0, feature_flags_1.areDeliveryRevisionsEnabled)();
+                    const revisionOfPending = Boolean(revisionsEnabled && pendingSnapshot && revisionOfDeliveryId
+                        && prDeliveryRevisionAllowed(pendingSnapshot, revisionOfDeliveryId, rail.ticketIds));
+                    if (revisionsEnabled && pendingSnapshot && revisionOfDeliveryId && !revisionOfPending) {
+                        res.status(409).json({
+                            error: 'invalid_revision_target',
+                            prDeliveryId: pendingSnapshot.id,
+                            detail: 'a revision must target the rail\'s active delivery and cover all of its specs',
+                        });
+                        return;
+                    }
+                    if (pendingSnapshot && !revisionOfPending && !prDeliveryContinuesTickets(pendingSnapshot, rail.ticketIds)) {
                         res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pendingSnapshot.id });
                         return;
                     }
+                    if (revisionOfPending && pendingSnapshot) {
+                        revisionRequest = {
+                            ofDeliveryId: pendingSnapshot.id,
+                            decision: pendingSnapshot.decision,
+                            note: revisionNote,
+                        };
+                    }
                     // Explicit target vs an undecided continuable delivery: the slot's
                     // active generation owns its PR. A DIFFERENT explicit target would
                     // append to the undecided branches → 409; the SAME PR is redundant
@@ -720,6 +811,9 @@ function createRailsRouter() {
                                 ...(typeof targetPrNumber === 'number' && !continuablePrDelivery
                                     ? { explicitPrTarget: { prNumber: targetPrNumber } }
                                     : {}),
+                                // Revision of an undecided delivery: the guard above proved the
+                                // exemption, so pass the contract through for supersession.
+                                ...(revisionRequest ? { revision: revisionRequest } : {}),
                             });
                             res.status(202).json({ loopRunIds: ids, railIndex, mode, isolated: true });
                             return;
@@ -999,6 +1093,33 @@ function createRailsRouter() {
         }
         res.json({ ok: true, jobIds: targetJobIds, loopRunIds: targetLoopRunIds, canceled: canceledCount });
     });
+    // GET /rails/pr-deliveries/:id/packet — the plain-language review packet for a
+    // settled delivery: composed server-side from durable rows only (no model
+    // calls, no live-store reads) plus the pre-resolved Accept ladder, so the
+    // client never has to ask the user to choose between git actions. Read-only.
+    router.get('/pr-deliveries/:prDeliveryId/packet', async (req, res) => {
+        if (!(0, feature_flags_1.isReviewPacketEnabled)()) {
+            res.status(404).json({ error: 'Not Found' });
+            return;
+        }
+        const c = ctx(req);
+        const row = (0, rail_pr_store_1.getPrDelivery)(c.db, req.params.prDeliveryId);
+        if (!row) {
+            res.status(404).json({ error: 'Delivery not found' });
+            return;
+        }
+        try {
+            const packet = (0, review_packet_1.composeReviewPacket)({ db: c.db, row });
+            // Capability probes are read-only and offline; a failure degrades to the
+            // confirm-gated local path rather than blocking the packet.
+            const acceptCapability = await (0, accept_ladder_1.resolveAcceptCapability)({ repoDir: c.project.path, exec: pr_publisher_1.defaultExec });
+            res.json({ packet, acceptCapability, snapshot: (0, rail_pr_store_1.toPrDeliverySnapshot)(row) });
+        }
+        catch (err) {
+            console.error('[rails-router] packet composition failed:', err);
+            res.status(500).json({ error: 'packet composition failed', detail: err.message });
+        }
+    });
     // POST /rails/pr-decision — the ONE decision action (safe-pr-review-flow) both
     // surfaces (dashboard rail row + agent-chat card) call on a rail_pr_deliveries
     // row: create-pr | publish | discard/dismiss | poll/reopen | merge-local |