specrails-desktop 2.34.1 → 2.36.0

package/server/dist/agent-defaults.js

@@ -0,0 +1,359 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentDefaultsValidationError = exports.GLOBAL_DEFAULTS_PROFILE_NAME = exports.AGENT_DEFAULTS_SETTING_KEY = void 0;
+exports.readAgentDefaultsSettings = readAgentDefaultsSettings;
+exports.applyAgentDefaultsPatch = applyAgentDefaultsPatch;
+exports.resolveAgentDefaults = resolveAgentDefaults;
+exports.mergeProfileWithAgentDefaults = mergeProfileWithAgentDefaults;
+exports.synthesizeProfileFromDefaults = synthesizeProfileFromDefaults;
+exports.ensureGlobalProfileSnapshot = ensureGlobalProfileSnapshot;
+exports.buildAgentDefaultsCatalog = buildAgentDefaultsCatalog;
+exports.createLoopProfilePathResolver = createLoopProfilePathResolver;
+/**
+ * Global Specrails Agents defaults — app-level (per-machine) per-provider
+ * customization of the specrails-core pipeline agents: the pipeline
+ * (orchestrator) model + reasoning effort, and per-agent model overrides for
+ * providers whose runtime honours execution profiles (claude, kimi).
+ *
+ * Storage is one JSON blob under `desktop_settings['specrails_agent_defaults']`
+ * (no migration — plain k/v). Every consumer reads AT SPAWN/LAUNCH TIME, so a
+ * settings change applies to the next run without restarting the app.
+ *
+ * Layering contract (least → most specific):
+ *   built-in adapter default  <  GLOBAL agent defaults  <  per-project setting
+ *   (orchestrator model, resolved model)  <  per-project profile  <  explicit
+ *   per-launch selection.
+ * The global layer therefore only ever fills gaps — it never overrides an
+ * explicit user choice made closer to the run.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const desktop_db_1 = require("./desktop-db");
+const providers_1 = require("./providers");
+const runtime_1 = require("./providers/runtime");
+exports.AGENT_DEFAULTS_SETTING_KEY = 'specrails_agent_defaults';
+/** Synthetic profile name recorded when a run's profile came purely from the
+ *  global defaults layer (no project profile existed). */
+exports.GLOBAL_DEFAULTS_PROFILE_NAME = 'global-defaults';
+/** Agent ids the v1 settings surface may override — the baseline pipeline trio
+ *  every adapter guarantees (`adapter.baselineAgents()`). */
+const AGENT_ID_PATTERN = /^(sr|custom)-[a-z0-9][a-z0-9-]*$/;
+class AgentDefaultsValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AgentDefaultsValidationError';
+    }
+}
+exports.AgentDefaultsValidationError = AgentDefaultsValidationError;
+const EMPTY_SETTINGS = { version: 1, providers: {} };
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Structural sanitize for values read from disk — never throws, drops junk. */
+function sanitizeStored(raw) {
+    if (!isRecord(raw) || !isRecord(raw.providers))
+        return { ...EMPTY_SETTINGS, providers: {} };
+    const providers = {};
+    for (const [id, value] of Object.entries(raw.providers)) {
+        if (!isRecord(value))
+            continue;
+        const entry = { custom: value.custom === true };
+        if (typeof value.pipelineModel === 'string' && value.pipelineModel)
+            entry.pipelineModel = value.pipelineModel;
+        if (typeof value.pipelineEffort === 'string' && value.pipelineEffort)
+            entry.pipelineEffort = value.pipelineEffort;
+        if (isRecord(value.agentModels)) {
+            const agents = {};
+            for (const [agentId, model] of Object.entries(value.agentModels)) {
+                if (AGENT_ID_PATTERN.test(agentId) && typeof model === 'string' && model)
+                    agents[agentId] = model;
+            }
+            if (Object.keys(agents).length > 0)
+                entry.agentModels = agents;
+        }
+        providers[id] = entry;
+    }
+    return { version: 1, providers };
+}
+/** Read + sanitize the stored settings. Never throws. */
+function readAgentDefaultsSettings(db) {
+    try {
+        const raw = (0, desktop_db_1.getDesktopSetting)(db, exports.AGENT_DEFAULTS_SETTING_KEY);
+        if (!raw)
+            return { ...EMPTY_SETTINGS, providers: {} };
+        return sanitizeStored(JSON.parse(raw));
+    }
+    catch {
+        return { ...EMPTY_SETTINGS, providers: {} };
+    }
+}
+/**
+ * Validate ONE provider's config from an untrusted PATCH body.
+ * Throws `AgentDefaultsValidationError` with an API-stable `code`.
+ */
+function validateProviderPatch(providerId, value) {
+    let adapter;
+    try {
+        adapter = (0, providers_1.getAdapter)(providerId);
+    }
+    catch {
+        throw new AgentDefaultsValidationError('unknown_provider', `Unknown provider "${providerId}"`);
+    }
+    if (!isRecord(value)) {
+        throw new AgentDefaultsValidationError('invalid_provider_config', `Config for "${providerId}" must be an object`);
+    }
+    const entry = { custom: value.custom === true };
+    if (value.pipelineModel !== undefined && value.pipelineModel !== null && value.pipelineModel !== '') {
+        if (!(0, runtime_1.isModelAvailableForAdapter)(adapter, value.pipelineModel)) {
+            throw new AgentDefaultsValidationError('invalid_model', `Model is not valid for provider "${providerId}"`);
+        }
+        entry.pipelineModel = value.pipelineModel;
+    }
+    if (value.pipelineEffort !== undefined && value.pipelineEffort !== null && value.pipelineEffort !== '') {
+        const effortModel = entry.pipelineModel ?? adapter.defaultModel();
+        if (!(0, runtime_1.isReasoningEffortValidForModel)(adapter, effortModel, value.pipelineEffort)) {
+            throw new AgentDefaultsValidationError('invalid_effort', `Effort is not valid for provider "${providerId}" and model "${effortModel}"`);
+        }
+        entry.pipelineEffort = value.pipelineEffort;
+    }
+    if (value.agentModels !== undefined && value.agentModels !== null) {
+        if (!isRecord(value.agentModels)) {
+            throw new AgentDefaultsValidationError('invalid_agent_models', 'agentModels must be an object');
+        }
+        const agents = {};
+        for (const [agentId, model] of Object.entries(value.agentModels)) {
+            if (model === undefined || model === null || model === '')
+                continue;
+            if (adapter.capabilities.profiles !== true) {
+                throw new AgentDefaultsValidationError('per_agent_not_supported', `Provider "${providerId}" does not support per-agent model overrides`);
+            }
+            if (!adapter.baselineAgents().includes(agentId)) {
+                throw new AgentDefaultsValidationError('unknown_agent', `Unknown agent "${agentId}" for provider "${providerId}"`);
+            }
+            if (!(0, runtime_1.isModelAvailableForAdapter)(adapter, model)) {
+                throw new AgentDefaultsValidationError('invalid_agent_model', `Model for "${agentId}" is not valid for provider "${providerId}"`);
+            }
+            agents[agentId] = model;
+        }
+        if (Object.keys(agents).length > 0)
+            entry.agentModels = agents;
+    }
+    return entry;
+}
+/**
+ * Apply a PATCH body: every provider key present REPLACES that provider's
+ * stored config wholesale (deterministic; no deep-merge ambiguity). Returns
+ * the canonical stored settings. Throws `AgentDefaultsValidationError`.
+ */
+function applyAgentDefaultsPatch(db, body) {
+    if (!isRecord(body) || !isRecord(body.providers)) {
+        throw new AgentDefaultsValidationError('invalid_body', "body must include a 'providers' object");
+    }
+    const next = readAgentDefaultsSettings(db);
+    for (const [providerId, value] of Object.entries(body.providers)) {
+        next.providers[providerId] = validateProviderPatch(providerId, value);
+    }
+    (0, desktop_db_1.setDesktopSetting)(db, exports.AGENT_DEFAULTS_SETTING_KEY, JSON.stringify(next));
+    return next;
+}
+/**
+ * Resolve the effective global defaults for one provider — validated against
+ * the adapter's live catalog so a stale stored model degrades to "no override"
+ * (fail-open to built-in defaults) instead of poisoning a spawn.
+ * Returns null when the layer is inactive or nothing survives validation.
+ */
+function resolveAgentDefaults(db, providerId) {
+    let adapter;
+    try {
+        adapter = (0, providers_1.getAdapter)(providerId);
+    }
+    catch {
+        return null;
+    }
+    const entry = readAgentDefaultsSettings(db).providers[providerId];
+    if (!entry?.custom)
+        return null;
+    const pipelineModel = entry.pipelineModel && (0, runtime_1.isModelAvailableForAdapter)(adapter, entry.pipelineModel) ? entry.pipelineModel : null;
+    const pipelineEffort = entry.pipelineEffort && adapter.capabilities.supportsReasoningEffort === true ? entry.pipelineEffort : null;
+    const agentModels = {};
+    if (adapter.capabilities.profiles === true && entry.agentModels) {
+        for (const [agentId, model] of Object.entries(entry.agentModels)) {
+            if (adapter.baselineAgents().includes(agentId)
+                && (0, runtime_1.isModelAvailableForAdapter)(adapter, model)) {
+                agentModels[agentId] = model;
+            }
+        }
+    }
+    if (!pipelineModel && !pipelineEffort && Object.keys(agentModels).length === 0)
+        return null;
+    return { pipelineModel, pipelineEffort, agentModels };
+}
+/**
+ * Fill a resolved profile's gaps from the global layer: only agents WITHOUT an
+ * explicit model get one. The profile's own choices (including orchestrator)
+ * always win. Returns the original object untouched when nothing changed.
+ */
+function mergeProfileWithAgentDefaults(profile, defaults) {
+    let changed = false;
+    const agents = profile.agents.map((agent) => {
+        if (!agent.model && defaults.agentModels[agent.id]) {
+            changed = true;
+            return { ...agent, model: defaults.agentModels[agent.id] };
+        }
+        return agent;
+    });
+    if (!changed)
+        return { changed: false, profile };
+    return { changed: true, profile: { ...profile, agents } };
+}
+/** Baseline-trio profile synthesized purely from the global layer (used when
+ *  the project has no profile of its own). */
+function synthesizeProfileFromDefaults(adapter, defaults) {
+    return {
+        schemaVersion: 1,
+        name: exports.GLOBAL_DEFAULTS_PROFILE_NAME,
+        description: 'Synthesized from the app-level Specrails Agents defaults',
+        provider: adapter.id,
+        orchestrator: { model: defaults.pipelineModel ?? adapter.defaultModel() },
+        agents: adapter.baselineAgents().map((id) => ({
+            id,
+            ...(defaults.agentModels[id] ? { model: defaults.agentModels[id] } : {}),
+        })),
+        routing: [{ default: true, agent: 'sr-developer' }],
+    };
+}
+/**
+ * Content-addressed snapshot for the LOOP path (no per-job dir exists when the
+ * engine spawns ai-steps). Identical content reuses the same immutable file, so
+ * concurrent runs never race and a settings change lands in a NEW file — an
+ * in-flight run keeps the profile it resolved. Never throws to the caller.
+ */
+function ensureGlobalProfileSnapshot(providerId, profile, baseDir = path.join(os.homedir(), '.specrails', 'agent-defaults')) {
+    const body = JSON.stringify(profile, null, 2) + '\n';
+    const hash = (0, crypto_1.createHash)('sha256').update(body).digest('hex').slice(0, 12);
+    const file = path.join(baseDir, `${providerId}-${hash}.json`);
+    if (fs.existsSync(file))
+        return file;
+    fs.mkdirSync(baseDir, { recursive: true });
+    const tmp = path.join(baseDir, `.${providerId}-${hash}.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, body, { encoding: 'utf8', mode: 0o444 });
+    try {
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // A concurrent writer won the rename — the content is identical by hash.
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* best-effort */ }
+    }
+    return file;
+}
+/** Catalog payload for the settings UI — every REGISTERED provider (detection
+ *  state is a client concern; undetected providers render non-clickable). */
+function buildAgentDefaultsCatalog() {
+    return (0, providers_1.listAdapters)().map((adapter) => {
+        const models = adapter.modelCatalog().map((m) => ({ ...m }));
+        const effortsByModel = {};
+        for (const m of models) {
+            effortsByModel[m.value] = [...(0, runtime_1.reasoningEffortsForModel)(adapter, m.value)];
+        }
+        return {
+            id: adapter.id,
+            displayName: adapter.displayName,
+            models,
+            defaultModel: adapter.defaultModel(),
+            baselineAgents: [...adapter.baselineAgents()],
+            perAgentModels: adapter.capabilities.profiles === true,
+            supportsEffort: adapter.capabilities.supportsReasoningEffort === true,
+            customModelAliases: adapter.capabilities.customModelAliases === true,
+            effortsByModel,
+        };
+    });
+}
+/**
+ * Loop-path profile resolver factory. Returns `(provider) => snapshotPath|null`
+ * for injection as `SPECRAILS_PROFILE_PATH` on loop ai-step spawns.
+ *
+ * Deliberately inert unless the global layer carries per-agent models for the
+ * provider — when inactive (or when the project profile already pins every
+ * agent) it returns null and the run behaves byte-identically to today (core
+ * resolves `.specrails/profiles/project-default.json` on its own).
+ */
+function createLoopProfilePathResolver(io) {
+    return (provider) => {
+        try {
+            const defaults = resolveAgentDefaults(io.desktopDb, provider);
+            if (!defaults || Object.keys(defaults.agentModels).length === 0)
+                return null;
+            const adapter = (0, providers_1.getAdapter)(provider);
+            if (adapter.capabilities.profiles !== true || adapter.capabilities.profileEnvSupport !== true)
+                return null;
+            const root = io.profileRoot();
+            if (!io.supportsProfiles(root))
+                return null;
+            let base = null;
+            try {
+                const resolve = io.resolveProfile
+                    ?? ((r, e, p) => require('./profile-manager').resolveProfile(r, e, p));
+                base = resolve(root, undefined, provider);
+            }
+            catch {
+                base = null;
+            }
+            let effective = null;
+            if (base) {
+                const merged = mergeProfileWithAgentDefaults(base.profile, defaults);
+                // Nothing to add ⇒ stay out of the way (core's own file fallback rules).
+                effective = merged.changed ? merged.profile : null;
+            }
+            else {
+                effective = synthesizeProfileFromDefaults(adapter, defaults);
+            }
+            if (!effective)
+                return null;
+            return ensureGlobalProfileSnapshot(provider, effective, io.snapshotDir);
+        }
+        catch (err) {
+            console.warn(`[agent-defaults] loop profile resolution failed for ${provider}: ${err.message}`);
+            return null;
+        }
+    };
+}

package/server/dist/agent-mcp-config.js

@@ -10,6 +10,7 @@ exports.mergeSpecrailsIntoWorkspaceMcp = mergeSpecrailsIntoWorkspaceMcp;
 exports.buildAgentMcpArgs = buildAgentMcpArgs;
 exports.removeAgentCapabilityFile = removeAgentCapabilityFile;
 exports.prepareAgentMcp = prepareAgentMcp;
+exports.syncExternalServersIntoJsonFile = syncExternalServersIntoJsonFile;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
@@ -18,6 +19,7 @@ const path_resolver_1 = require("./path-resolver");
 const win_spawn_1 = require("./util/win-spawn");
 const agent_tier_1 = require("./agent-tier");
 const providers_1 = require("./providers");
+const external_mcp_1 = require("./external-mcp");
 const AGENT_CONVERSATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 // ─── Agent MCP wiring (design D8 / D1) ────────────────────────────────────────
 //
@@ -141,7 +143,13 @@ function buildAgentMcpArgs(opts) {
         return [];
     const dir = agentDir(opts.conversationId);
     const file = path_1.default.join(dir, 'mcp.json');
-    fs_1.default.writeFileSync(file, JSON.stringify({ mcpServers: { specrails: entry } }, null, 2), { mode: 0o600 });
+    const mcpServers = { specrails: entry };
+    for (const server of opts.external ?? []) {
+        if (server.name === 'specrails')
+            continue;
+        mcpServers[server.name] = server.config;
+    }
+    fs_1.default.writeFileSync(file, JSON.stringify({ mcpServers }, null, 2), { mode: 0o600 });
     try {
         fs_1.default.chmodSync(file, 0o600);
     }
@@ -228,6 +236,27 @@ function codexMcpOverrides(entry) {
     }
     return args;
 }
+/** External-server variant of the codex `-c` overrides. Callers pre-filter with
+ *  `isCodexInjectable` (TOML-safe name + string command). */
+function codexExternalOverrides(server) {
+    const c = (kv) => ['-c', kv];
+    const command = String(server.config.command);
+    const argsList = Array.isArray(server.config.args)
+        ? server.config.args.filter((a) => typeof a === 'string')
+        : [];
+    const args = [
+        ...c(`mcp_servers.${server.name}.command=${JSON.stringify(command)}`),
+        ...c(`mcp_servers.${server.name}.args=[${argsList.map((a) => JSON.stringify(a)).join(', ')}]`),
+    ];
+    const env = server.config.env;
+    if (env && typeof env === 'object' && !Array.isArray(env)) {
+        for (const [k, v] of Object.entries(env)) {
+            if (typeof v === 'string')
+                args.push(...c(`mcp_servers.${server.name}.env.${k}=${JSON.stringify(v)}`));
+        }
+    }
+    return args;
+}
 /**
  * Prepares the specrails MCP for the given provider and returns the spawn
  * extraArgs + env to merge. Returns empty wiring when the bridge is unavailable
@@ -235,6 +264,7 @@ function codexMcpOverrides(entry) {
  */
 function prepareAgentMcp(opts) {
     const adapter = (0, providers_1.getAdapter)(opts.adapterId);
+    const external = (opts.external ?? []).filter((s) => s.name !== 'specrails');
     if (adapter.id === 'claude') {
         return { extraArgs: buildAgentMcpArgs(opts), env: {} };
     }
@@ -243,12 +273,14 @@ function prepareAgentMcp(opts) {
         return { extraArgs: [], env: {} };
     if (adapter.mcpRegistration === 'cli-add') {
         // Inline -c overrides contain only the capability FILE PATH, never its secret.
-        return { extraArgs: codexMcpOverrides(entry), env: {} };
+        const externalArgs = external.filter(external_mcp_1.isCodexInjectable).flatMap(codexExternalOverrides);
+        return { extraArgs: [...codexMcpOverrides(entry), ...externalArgs], env: {} };
     }
     // Project-json providers write only their native project config in the
     // conversation-isolated cwd.
     const file = adapter.projectMcpPath?.(opts.cwd) ?? path_1.default.join(opts.cwd, '.mcp.json');
     mergeServerIntoJsonFile(file, entry);
+    syncExternalServersIntoJsonFile(file, external);
     if (adapter.id === 'gemini') {
         // gemini-cli has NEVER read .mcp.json (a Claude convention) — its only MCP
         // surface is `mcpServers` in settings.json (user or <cwd>/.gemini project
@@ -286,3 +318,63 @@ function mergeServerIntoJsonFile(file, entry) {
     }
     catch { /* best-effort */ }
 }
+/**
+ * Sync the user's EXTERNAL servers into a persistent settings file (gemini
+ * `.gemini/settings.json`, kimi `.kimi-code/mcp.json`) with owned-key hygiene:
+ * a sidecar (`external-owned.json`, same dir) records every key the app wrote,
+ * and each spawn removes the previously-owned set before merging the currently
+ * enabled one — so disabling an entry removes it on the next spawn while keys
+ * the app never wrote (and `specrails`, managed separately) are untouched.
+ */
+function syncExternalServersIntoJsonFile(file, external) {
+    const dir = path_1.default.dirname(file);
+    const sidecar = path_1.default.join(dir, 'external-owned.json');
+    let owned = [];
+    try {
+        const parsed = JSON.parse(fs_1.default.readFileSync(sidecar, 'utf-8'));
+        if (parsed && Array.isArray(parsed.owned)) {
+            owned = parsed.owned.filter((n) => typeof n === 'string');
+        }
+    }
+    catch {
+        /* first spawn / no sidecar yet */
+    }
+    // Nothing owned before and nothing to inject now → leave the file alone.
+    if (owned.length === 0 && external.length === 0)
+        return;
+    let current = {};
+    try {
+        if (fs_1.default.existsSync(file)) {
+            const parsed = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+            if (parsed && typeof parsed === 'object')
+                current = parsed;
+        }
+    }
+    catch {
+        current = {};
+    }
+    const mcpServers = { ...(current.mcpServers ?? {}) };
+    for (const name of owned) {
+        if (name !== 'specrails')
+            delete mcpServers[name];
+    }
+    const nextOwned = [];
+    for (const server of external) {
+        if (server.name === 'specrails')
+            continue;
+        mcpServers[server.name] = server.config;
+        nextOwned.push(server.name);
+    }
+    const next = { ...current, mcpServers };
+    fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs_1.default.writeFileSync(file, JSON.stringify(next, null, 2), { mode: 0o600 });
+    try {
+        fs_1.default.chmodSync(file, 0o600);
+    }
+    catch { /* best-effort */ }
+    fs_1.default.writeFileSync(sidecar, JSON.stringify({ owned: nextOwned }, null, 2), { mode: 0o600 });
+    try {
+        fs_1.default.chmodSync(sidecar, 0o600);
+    }
+    catch { /* best-effort */ }
+}

package/server/dist/agent-operator-prompt.js

@@ -69,6 +69,10 @@ coding pipelines over them.
   \`mcp_specrails_<canonical name>\` (e.g. \`mcp_specrails_specrails_specs\`).
   Use whatever form your tool list shows; they are identical tools. They are
   MCP tools, NOT shell commands or files — never hunt for them on disk.
+- Additional USER-CONFIGURED tools (external MCP servers) may also appear in
+  your tool list. Use them for their own domains when helpful, but ALL
+  Specrails app operations (specs, rails, jobs, projects, …) MUST still go
+  through the \`specrails_*\` tools — never through a lookalike external tool.
 - Target a project with \`specrails_select_project\` (or the \`projectId\`
   argument). If none is pinned ("Home") and the request is project-specific, ASK
   whether to create a project or search across all — do not guess.
@@ -428,11 +432,19 @@ summary later.
   relaunch strategy even when \`main\` did not have that spec before the PR. If
   asked why a strategy was chosen, verify against active PR contents before
   answering.
-- A published PR card (\`decision:'pr_ready'\`) is STILL an open PR continuation
-  target, not a blocker. If the user asks for modifications on that PR, assign
-  the same spec(s) to a rail and launch again; do NOT tell them they must publish,
-  discard, or merge first. \`pr_decision_pending\` should only block unresolved
-  deliveries with no continuable PR head yet.
+- **"Change something about work already delivered" = a REVISION launch.** When
+  the user asks for a modification to a delivery that is awaiting their decision
+  (any non-terminal card: \`on_review\`, \`pr_draft\`, \`pr_ready\`, \`no_changes\`,
+  \`implementation_failed\`), call \`specrails_rails(launch)\` with
+  \`revisionOfDeliveryId\` = that card's \`prDeliveryId\` and \`revisionNote\` = what
+  they asked for, in their own words. Do NOT tell them to publish, discard or
+  merge first, and do NOT relaunch the ordinary implement/batch mode: a revision
+  runs a dedicated Architect-less loop that builds on the existing branch instead
+  of re-planning from scratch. The rail must still carry exactly that delivery's
+  specs; a mismatch returns \`invalid_revision_target\`, which means re-check the
+  rail's spec assignment rather than retrying blindly.
+- \`pr_decision_pending\` therefore only blocks a launch that is neither a
+  revision nor a continuation of an open PR head.
 - Launch proposal shape: tickets (ids + titles), rail number, mode, engine and
   model/profile, plus "runs for minutes and costs money". If the API mode is
   \`freestyle\`, write "Freestyle" to the user. Wait for yes.

package/server/dist/browser-playwright.js

@@ -495,13 +495,50 @@ class PlaywrightPageHandle {
         // target=_blank, OAuth login windows). The popup lives in the SAME browser
         // context — cookies and the window.opener/postMessage relationship are
         // intact, which is exactly what an OAuth redirect/popup flow needs.
+        //
+        // HARDENING (Okta-class IdPs): a popup opened from a cross-origin IFRAME
+        // (out-of-process sign-in widgets) is attributed to the iframe's target,
+        // and the page-level 'popup' event can miss it — the login window then
+        // "never appears". So we ALSO watch the shared context for new pages whose
+        // opener chain resolves to this page and adopt those. `seen` dedupes the
+        // two doors; pages from other sessions have a different opener and are
+        // ignored.
         try {
-            this.page.on('popup', (p) => {
+            const seen = new WeakSet();
+            const adopt = (p) => {
+                if (seen.has(p))
+                    return;
+                seen.add(p);
                 try {
                     cb(new PlaywrightPageHandle(p));
                 }
                 catch { /* never break the event loop */ }
-            });
+            };
+            this.page.on('popup', adopt);
+            const ctx = this.page.context?.();
+            if (ctx?.on) {
+                const onContextPage = (p) => {
+                    void (async () => {
+                        try {
+                            if (seen.has(p) || p === this.page)
+                                return;
+                            const opener = await p.opener?.();
+                            if (opener === this.page)
+                                adopt(p);
+                        }
+                        catch { /* ignore */ }
+                    })();
+                };
+                ctx.on('page', onContextPage);
+                // The shared context outlives this page — detach on page close so a
+                // long-lived app never accumulates dead listeners.
+                this.page.on('close', () => {
+                    try {
+                        ctx.off?.('page', onContextPage);
+                    }
+                    catch { /* ignore */ }
+                });
+            }
         }
         catch { /* ignore */ }
     }

package/server/dist/db.js

@@ -1464,6 +1464,43 @@ const MIGRATIONS = [
         ON agent_tests(provider, agent_name)
     `);
     },
+    // Migration 56: nontech-review-experience Wave 1 — two additive nullable
+    // JSON columns on rail_pr_deliveries. `spec_snapshot` freezes each covered
+    // ticket's title/description/labels at LAUNCH so the review packet renders
+    // what the user actually asked (the live store can be edited mid-run).
+    // `settle_evidence` persists the deterministic settle-time harvest (the
+    // VERIFICATION sentinel, the verify step's output tail, the reviewer's
+    // confidence-score.json) captured BEFORE worktree release — the packet's
+    // proof sections survive worktree teardown. NULL on legacy rows = honest
+    // "not captured". Additive + idempotent (guarded by PRAGMA table_info).
+    (db) => {
+        const cols = db.prepare(`PRAGMA table_info(rail_pr_deliveries)`).all()
+            .map((r) => r.name);
+        if (!cols.includes('spec_snapshot')) {
+            db.exec(`ALTER TABLE rail_pr_deliveries ADD COLUMN spec_snapshot TEXT`);
+        }
+        if (!cols.includes('settle_evidence')) {
+            db.exec(`ALTER TABLE rail_pr_deliveries ADD COLUMN settle_evidence TEXT`);
+        }
+    },
+    // Migration 57: nontech-review-experience Wave 3 — revision metadata on the
+    // NEW delivery generation a revision creates. `revision_note` is the user's
+    // one-sentence instruction (so packet v2 can show what was asked to change)
+    // and `revision_of` points at the generation being revised. Deliberately NOT
+    // a new `decision` value: an unknown decision makes older clients drop the
+    // whole PR card, and the shipped generation/supersession model already
+    // expresses "a newer attempt replaced the previous one". Additive +
+    // idempotent; NULL on every pre-existing row and on ordinary launches.
+    (db) => {
+        const cols = db.prepare(`PRAGMA table_info(rail_pr_deliveries)`).all()
+            .map((r) => r.name);
+        if (!cols.includes('revision_note')) {
+            db.exec(`ALTER TABLE rail_pr_deliveries ADD COLUMN revision_note TEXT`);
+        }
+        if (!cols.includes('revision_of')) {
+            db.exec(`ALTER TABLE rail_pr_deliveries ADD COLUMN revision_of TEXT`);
+        }
+    },
 ];
 function applyMigrations(db) {
     // Ensure the migrations table exists (migration 1 creates it, but we need
@@ -2019,6 +2056,7 @@ function getProjectSettings(db) {
     return {
         pipelineTelemetryEnabled: telemetryRow?.value === 'true',
         orchestratorModel: modelRow?.value ?? 'sonnet',
+        orchestratorModelExplicit: modelRow?.value !== undefined,
         prePrompt: prePromptRow?.value ?? '',
         freestylePrePrompt: freestylePrePromptRow?.value ?? '',
         integrationBranch: integrationBranchRow?.value ?? '',