specrails-desktop 2.29.1 → 2.29.2

package/server/dist/agent-cwd-manager.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.agentCwdPath = agentCwdPath;
 exports.ensureAgentCwd = ensureAgentCwd;
+exports.agentConversationCwdPath = agentConversationCwdPath;
+exports.ensureAgentConversationCwd = ensureAgentConversationCwd;
 exports.removeAgentCwd = removeAgentCwd;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -14,9 +16,10 @@ const agent_operator_prompt_1 = require("./agent-operator-prompt");
 //
 // The agent chat spawns the AI CLI from an app-owned cwd (NOT a project path), so
 // no project's CLAUDE.md is auto-loaded and the agent starts with a focused
-// "operator" stance. Mirrors explore-cwd-manager but is app-global (one dir, no
-// project symlink). The operator instructions are written for every provider
-// (CLAUDE.md / AGENTS.md / GEMINI.md) so the chosen CLI picks them up.
+// "operator" stance. Claude/Codex retain the original app-global cwd. Gemini
+// gets a per-conversation child cwd because it discovers project MCP settings
+// from `<cwd>/.gemini/settings.json`; sharing that file would let concurrent
+// conversations overwrite each other's capability-file reference.
 function homeDir() {
     return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
 }
@@ -24,20 +27,61 @@ function agentCwdPath() {
     return path_1.default.join(homeDir(), '.specrails', 'agent-cwd');
 }
 const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
+const AGENT_CONVERSATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+function ensureCwd(dir) {
+    fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+    }
+    catch { /* best-effort on platforms without chmod */ }
+    for (const name of INSTRUCTION_FILES) {
+        // App-owned files (not user-edited) — always (re)write so operator-prompt
+        // updates take effect instead of being pinned to the first materialization.
+        fs_1.default.writeFileSync(path_1.default.join(dir, name), agent_operator_prompt_1.OPERATOR_INSTRUCTIONS, 'utf-8');
+    }
+    return dir;
+}
 /**
  * Ensures the app-level agent cwd exists with operator instruction files.
  * Idempotent; safe to call on every turn. Returns the cwd path.
  */
 function ensureAgentCwd() {
     const dir = agentCwdPath();
-    fs_1.default.mkdirSync(dir, { recursive: true });
-    for (const name of INSTRUCTION_FILES) {
-        // App-owned files (not user-edited) — always (re)write so operator-prompt
-        // updates take effect instead of being pinned to the first materialization.
-        fs_1.default.writeFileSync(path_1.default.join(dir, name), agent_operator_prompt_1.OPERATOR_INSTRUCTIONS, 'utf-8');
+    ensureCwd(dir);
+    // Older builds wrote Gemini's per-turn MCP registration into this shared cwd.
+    // Claude also discovers `.mcp.json` from cwd, so leaving that stale file in
+    // place could make a later Claude turn load another conversation's still-live
+    // capability. This directory is wholly app-owned; remove only those legacy
+    // generated config files while preserving the operator instructions.
+    try {
+        fs_1.default.unlinkSync(path_1.default.join(dir, '.mcp.json'));
+    }
+    catch { /* absent */ }
+    try {
+        fs_1.default.unlinkSync(path_1.default.join(dir, '.gemini', 'settings.json'));
+    }
+    catch { /* absent */ }
+    try {
+        fs_1.default.rmdirSync(path_1.default.join(dir, '.gemini'));
     }
+    catch { /* non-empty / absent */ }
     return dir;
 }
+/** Path for provider state that must not be shared across agent conversations. */
+function agentConversationCwdPath(conversationId) {
+    if (!AGENT_CONVERSATION_ID_RE.test(conversationId)) {
+        throw new Error(`unsafe agent conversation id: ${conversationId}`);
+    }
+    return path_1.default.join(agentCwdPath(), 'conversations', conversationId);
+}
+/**
+ * Materialise an isolated agent cwd for one conversation. Gemini uses this so
+ * its cwd-discovered `.mcp.json` and `.gemini/settings.json` can never be
+ * overwritten by a concurrent turn belonging to another conversation.
+ */
+function ensureAgentConversationCwd(conversationId) {
+    return ensureCwd(agentConversationCwdPath(conversationId));
+}
 /** Removes the agent cwd (used on full teardown / reset). Best-effort. */
 function removeAgentCwd() {
     try {

package/server/dist/agent-generator.js

@@ -12,6 +12,8 @@ const cli_prompt_1 = require("./util/cli-prompt");
 const providers_1 = require("./providers");
 const result_event_1 = require("./result-event");
 const ai_invocations_1 = require("./ai-invocations");
+const process_admission_1 = require("./process-admission");
+const transient_children_1 = require("./transient-children");
 const AGENT_STUDIO_ADAPTER = (0, providers_1.getAdapter)('claude');
 /**
  * Finalise the accumulated adapter events (native cost, or pricing-table
@@ -77,6 +79,9 @@ function escalateKill(child) {
     }
 }
 async function generateCustomAgent(cwd, opts) {
+    const admission = opts.record
+        ? (0, process_admission_1.captureProcessAdmission)(opts.record.projectId)
+        : (0, process_admission_1.captureProcessAdmission)();
     const systemPrompt = [
         'You are a specrails agent-authoring assistant.',
         '',
@@ -105,7 +110,11 @@ async function generateCustomAgent(cwd, opts) {
     ].join('\n');
     return new Promise((resolve, reject) => {
         const child = (0, cli_prompt_1.spawnClaude)([
-            '--dangerously-skip-permissions',
+            // This is a pure text transformation. The non-existent sentinel is
+            // intentional: an empty tool list is dropped by some Claude versions
+            // and silently restores the default toolkit.
+            '--tools',
+            '__none__',
             '--output-format',
             'stream-json',
             '--verbose',
@@ -118,18 +127,30 @@ async function generateCustomAgent(cwd, opts) {
             stdio: ['ignore', 'pipe', 'pipe'],
             cwd,
         });
+        if (opts.record)
+            (0, transient_children_1.trackTransientChild)(opts.record.projectId, child);
         let collected = '';
         // Accumulate adapter events so a killed/failed generate run is still costed
         // from the per-assistant-event usage snapshots (MED-3).
         const adapterEvents = [];
         const startedAt = new Date().toISOString();
         const record = opts.record;
+        let settled = false;
+        const settle = (status, complete) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(killer);
+            if (record && admission.isCurrent()) {
+                recordAgentStudioInvocation(record, adapterEvents, status, startedAt);
+            }
+            complete();
+        };
         const killer = setTimeout(() => {
-            escalateKill(child);
-            // Timeout kill — cost whatever tokens were burned before the SIGTERM.
-            if (record)
-                recordAgentStudioInvocation(record, adapterEvents, 'aborted', startedAt);
-            reject(new Error('agent generation timed out after 90s'));
+            settle('aborted', () => {
+                escalateKill(child);
+                reject(new Error('agent generation timed out after 90s'));
+            });
         }, 90_000);
         const reader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
         reader.on('line', (line) => {
@@ -164,27 +185,28 @@ async function generateCustomAgent(cwd, opts) {
         let stderr = '';
         child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
         child.on('error', (err) => {
-            clearTimeout(killer);
-            if (record)
-                recordAgentStudioInvocation(record, adapterEvents, 'failed', startedAt);
-            reject(err);
+            settle('failed', () => reject(admission.isCurrent()
+                ? err
+                : new process_admission_1.ProcessAdmissionClosedError(opts.record?.projectId)));
         });
         child.on('close', (code) => {
-            clearTimeout(killer);
-            const trimmed = collected.trim();
-            if (record) {
-                const status = code === 0 && trimmed ? 'success' : 'failed';
-                recordAgentStudioInvocation(record, adapterEvents, status, startedAt);
-            }
-            if (code !== 0) {
-                reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
-                return;
-            }
-            if (!trimmed) {
-                reject(new Error('claude returned empty output'));
+            if (!admission.isCurrent()) {
+                settle('aborted', () => reject(new process_admission_1.ProcessAdmissionClosedError(opts.record?.projectId)));
                 return;
             }
-            resolve(trimmed);
+            const trimmed = collected.trim();
+            const status = code === 0 && trimmed ? 'success' : 'failed';
+            settle(status, () => {
+                if (code !== 0) {
+                    reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
+                    return;
+                }
+                if (!trimmed) {
+                    reject(new Error('claude returned empty output'));
+                    return;
+                }
+                resolve(trimmed);
+            });
         });
     });
 }
@@ -200,6 +222,9 @@ async function generateCustomAgent(cwd, opts) {
  * can override via `tokenCeiling`).
  */
 async function testCustomAgent(cwd, opts) {
+    const admission = opts.record
+        ? (0, process_admission_1.captureProcessAdmission)(opts.record.projectId)
+        : (0, process_admission_1.captureProcessAdmission)();
     const tokenCeiling = opts.tokenCeiling ?? 4000;
     // Strip YAML frontmatter so we feed only the agent's instructions.
     const body = opts.draftBody.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
@@ -219,7 +244,10 @@ async function testCustomAgent(cwd, opts) {
     const started = Date.now();
     return new Promise((resolve, reject) => {
         const child = (0, cli_prompt_1.spawnClaude)([
-            '--dangerously-skip-permissions',
+            // A Studio smoke test evaluates the supplied instructions and returns
+            // text; it never needs authority over the project it is testing in.
+            '--tools',
+            '__none__',
             '--output-format',
             'stream-json',
             '--verbose',
@@ -232,6 +260,8 @@ async function testCustomAgent(cwd, opts) {
             stdio: ['ignore', 'pipe', 'pipe'],
             cwd,
         });
+        if (opts.record)
+            (0, transient_children_1.trackTransientChild)(opts.record.projectId, child);
         let collected = '';
         // LOW-14 double-count fix: the claude stream emits `message.usage` on EVERY
         // assistant frame AND a top-level cumulative `usage` on the terminal `result`
@@ -253,11 +283,22 @@ async function testCustomAgent(cwd, opts) {
         const runningTotalTokens = () => resultTokensIn !== undefined || resultTokensOut !== undefined
             ? (resultTokensIn ?? 0) + (resultTokensOut ?? 0)
             : msgTokensIn + msgTokensOut;
+        let settled = false;
+        const settle = (status, complete) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(killer);
+            if (record && admission.isCurrent()) {
+                recordAgentStudioInvocation(record, adapterEvents, status, startedAt);
+            }
+            complete();
+        };
         const killer = setTimeout(() => {
-            escalateKill(child);
-            if (record)
-                recordAgentStudioInvocation(record, adapterEvents, 'aborted', startedAt);
-            reject(new Error('test agent run timed out after 120s'));
+            settle('aborted', () => {
+                escalateKill(child);
+                reject(new Error('test agent run timed out after 120s'));
+            });
         }, 120_000);
         const reader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
         reader.on('line', (line) => {
@@ -318,30 +359,31 @@ async function testCustomAgent(cwd, opts) {
         let stderr = '';
         child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
         child.on('error', (err) => {
-            clearTimeout(killer);
-            if (record)
-                recordAgentStudioInvocation(record, adapterEvents, 'failed', startedAt);
-            reject(err);
+            settle('failed', () => reject(admission.isCurrent()
+                ? err
+                : new process_admission_1.ProcessAdmissionClosedError(opts.record?.projectId)));
         });
         child.on('close', (code) => {
-            clearTimeout(killer);
-            const durationMs = Date.now() - started;
-            const failedHard = !truncated && code !== 0 && !collected;
-            if (record) {
-                const status = truncated ? 'aborted' : failedHard ? 'failed' : 'success';
-                recordAgentStudioInvocation(record, adapterEvents, status, startedAt);
-            }
-            if (failedHard) {
-                reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
+            if (!admission.isCurrent()) {
+                settle('aborted', () => reject(new process_admission_1.ProcessAdmissionClosedError(opts.record?.projectId)));
                 return;
             }
-            resolve({
-                output: truncated
-                    ? collected + `\n\n[… output truncated after reaching ${tokenCeiling}-token ceiling]`
-                    : collected,
-                tokens: runningTotalTokens(),
-                durationMs,
-                draftHash,
+            const durationMs = Date.now() - started;
+            const failedHard = !truncated && code !== 0 && !collected;
+            const status = truncated ? 'aborted' : failedHard ? 'failed' : 'success';
+            settle(status, () => {
+                if (failedHard) {
+                    reject(new Error(`claude exited with code ${code}${stderr ? `: ${stderr.slice(-500)}` : ''}`));
+                    return;
+                }
+                resolve({
+                    output: truncated
+                        ? collected + `\n\n[… output truncated after reaching ${tokenCeiling}-token ceiling]`
+                        : collected,
+                    tokens: runningTotalTokens(),
+                    durationMs,
+                    draftHash,
+                });
             });
         });
     });

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

@@ -8,22 +8,26 @@ exports.resolveNodeCommand = resolveNodeCommand;
 exports.buildSpecrailsMcpEntry = buildSpecrailsMcpEntry;
 exports.mergeSpecrailsIntoWorkspaceMcp = mergeSpecrailsIntoWorkspaceMcp;
 exports.buildAgentMcpArgs = buildAgentMcpArgs;
+exports.removeAgentCapabilityFile = removeAgentCapabilityFile;
 exports.prepareAgentMcp = prepareAgentMcp;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const crypto_1 = require("crypto");
 const path_resolver_1 = require("./path-resolver");
 const win_spawn_1 = require("./util/win-spawn");
 const agent_tier_1 = require("./agent-tier");
+const AGENT_CONVERSATION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 // ─── Agent MCP wiring (design D8 / D1) ────────────────────────────────────────
 //
 // The in-app agent drives the app by talking to its OWN embedded MCP server. We
 // spawn the AI CLI with `--mcp-config` pointing at a generated config whose sole
 // server is the bundled `specrails-mcp` stdio bridge, which relays to
 // `127.0.0.1:<port>/api/mcp` and reads the scoped token from disk (no token is
-// ever written into the config file). The current Shift+Tab ladder level is
-// forwarded via env → the bridge sets it as a loopback-only header so the tool
-// guard enforces the agent ladder independently of the external Settings tiers.
+// ever written into the config file). A per-turn, server-minted capability is
+// written to a 0600 file and the config carries only that file path. The bridge
+// reads the secret and presents it to the server; tier/project/conversation are
+// derived from the server-side capability binding, never client headers.
 function homeDir() {
     return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
 }
@@ -75,9 +79,6 @@ function resolveBridgeScript() {
 function resolveNodeCommand() {
     return (0, path_resolver_1.resolveBundledNodeExe)() ?? 'node';
 }
-/** The launch-route contract for an origin conversation id (safe-pr-review-flow):
- *  must match rails-router's validation so a tagged launch is never 400'd. */
-const ORIGIN_CONVERSATION_ID_RE = /^[A-Za-z0-9-]{1,64}$/;
 /** Build the `mcpServers.specrails` entry the agent (or a project workspace) uses. */
 function buildSpecrailsMcpEntry(opts) {
     const bridge = resolveBridgeScript();
@@ -89,13 +90,8 @@ function buildSpecrailsMcpEntry(opts) {
     // Preserve the test-home override so the bridge reads the right token file.
     if (process.env.SPECRAILS_REGISTRY_HOME)
         env.SPECRAILS_REGISTRY_HOME = process.env.SPECRAILS_REGISTRY_HOME;
-    if (opts.tierLevel != null)
-        env[agent_tier_1.AGENT_TIER_ENV] = (0, agent_tier_1.tierNameForLevel)(opts.tierLevel);
-    if (opts.activeProjectId)
-        env[agent_tier_1.AGENT_PROJECT_ENV] = opts.activeProjectId;
-    if (opts.conversationId && ORIGIN_CONVERSATION_ID_RE.test(opts.conversationId)) {
-        env[agent_tier_1.AGENT_CONVERSATION_ENV] = opts.conversationId;
-    }
+    if (opts.capabilityFile)
+        env[agent_tier_1.AGENT_CAPABILITY_FILE_ENV] = opts.capabilityFile;
     return { command: resolveNodeCommand(), args: [bridge], env };
 }
 /**
@@ -138,19 +134,10 @@ function mergeSpecrailsIntoWorkspaceMcp(workspaceDir, port) {
  * `[]` when the bridge can't be located (agent then runs tool-less / degraded).
  */
 function buildAgentMcpArgs(opts) {
-    const entry = buildSpecrailsMcpEntry({
-        port: opts.port,
-        tierLevel: opts.tierLevel,
-        activeProjectId: opts.activeProjectId,
-        conversationId: opts.conversationId,
-    });
+    const entry = buildAgentTurnEntry(opts);
     if (!entry)
         return [];
-    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(opts.conversationId)) {
-        throw new Error(`unsafe agent conversation id: ${opts.conversationId}`);
-    }
-    const dir = path_1.default.join(homeDir(), '.specrails', 'agent', opts.conversationId);
-    fs_1.default.mkdirSync(dir, { recursive: true });
+    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 });
     try {
@@ -162,13 +149,64 @@ function buildAgentMcpArgs(opts) {
     return ['--mcp-config', file];
 }
 function agentDir(conversationId) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(conversationId)) {
+    if (!AGENT_CONVERSATION_ID_RE.test(conversationId)) {
         throw new Error(`unsafe agent conversation id: ${conversationId}`);
     }
     const dir = path_1.default.join(homeDir(), '.specrails', 'agent', conversationId);
-    fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+    }
+    catch { /* best-effort on platforms without chmod */ }
     return dir;
 }
+function capabilityFilePath(conversationId) {
+    return path_1.default.join(agentDir(conversationId), 'mcp.capability');
+}
+function buildAgentTurnEntry(opts) {
+    const capabilityFile = capabilityFilePath(opts.conversationId);
+    const entry = buildSpecrailsMcpEntry({ port: opts.port, capabilityFile });
+    if (!entry)
+        return null;
+    const tmp = `${capabilityFile}.tmp-${process.pid}-${(0, crypto_1.randomBytes)(8).toString('hex')}`;
+    try {
+        // `wx` prevents a pre-planted symlink from redirecting the bearer write.
+        fs_1.default.writeFileSync(tmp, opts.capability, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        try {
+            fs_1.default.chmodSync(tmp, 0o600);
+        }
+        catch { /* best-effort on platforms without chmod */ }
+        // Windows rename does not replace an existing destination. A stale file can
+        // remain after a hard crash, but its server-side capability is already gone.
+        try {
+            fs_1.default.unlinkSync(capabilityFile);
+        }
+        catch { /* first turn / already absent */ }
+        fs_1.default.renameSync(tmp, capabilityFile);
+        try {
+            fs_1.default.chmodSync(capabilityFile, 0o600);
+        }
+        catch { /* best-effort on platforms without chmod */ }
+    }
+    catch (err) {
+        try {
+            fs_1.default.unlinkSync(tmp);
+        }
+        catch { /* never leave a bearer-bearing temp file */ }
+        throw err;
+    }
+    return entry;
+}
+/** Delete the on-disk bearer as soon as its owning agent turn settles. */
+function removeAgentCapabilityFile(conversationId) {
+    if (!AGENT_CONVERSATION_ID_RE.test(conversationId))
+        return;
+    const file = path_1.default.join(homeDir(), '.specrails', 'agent', conversationId, 'mcp.capability');
+    try {
+        fs_1.default.unlinkSync(file);
+    }
+    catch { /* absent/already removed */ }
+}
 /**
  * Codex registers the specrails MCP via inline `-c mcp_servers.specrails.*`
  * config overrides. This keeps codex on the USER's real CODEX_HOME (auth + model
@@ -194,21 +232,16 @@ function codexMcpOverrides(entry) {
  * (agent then runs tool-less / degraded).
  */
 function prepareAgentMcp(opts) {
-    const entry = buildSpecrailsMcpEntry({
-        port: opts.port,
-        tierLevel: opts.tierLevel,
-        activeProjectId: opts.activeProjectId,
-        conversationId: opts.conversationId,
-    });
+    if (opts.adapterId === 'claude') {
+        return { extraArgs: buildAgentMcpArgs(opts), env: {} };
+    }
+    const entry = buildAgentTurnEntry(opts);
     if (!entry)
         return { extraArgs: [], env: {} };
     if (opts.adapterId === 'codex') {
-        // Inline -c overrides — no CODEX_HOME override, no file mutation; auth intact.
+        // Inline -c overrides contain only the capability FILE PATH, never its secret.
         return { extraArgs: codexMcpOverrides(entry), env: {} };
     }
-    if (opts.adapterId === 'claude') {
-        return { extraArgs: buildAgentMcpArgs(opts), env: {} };
-    }
     // gemini + any other project-json provider: write .mcp.json in the spawn cwd.
     const file = path_1.default.join(opts.cwd, '.mcp.json');
     mergeServerIntoJsonFile(file, entry);

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

@@ -438,7 +438,8 @@ summary later.
   server/watch/tail command that should keep running (for example \`npm run dev\`,
   \`vite --host\`, \`tail -f\`, or a local service), propose
   \`specrails_jobs(background_start)\` with the command, project and cwd, wait for
-  explicit yes, then call that tool with \`confirmed:true\`. Do NOT use a raw shell/background-task
+  explicit yes, ensure the permission level is Autonomous, then call that tool
+  with \`confirmed:true\`. Do NOT use a raw shell/background-task
   runner for these requests: only \`background_start\` emits the app events that
   create the killable chip above this agent chat's composer. You normally do not
   need to pass \`chatId\`; the in-app MCP origin conversation owns it. If a
@@ -519,4 +520,4 @@ When the user has no projects yet, or asks to add one:
 Setup is QUICK-only (fast, offline). Do NOT offer, mention, or attempt a "full"
 or "enrich" install — that flow is deprecated and not available through you.
 `;
-exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; support/troubleshooting/install/usage/job-failure questions use specrails_support first and never become specs unless the user pivots to product work; missing agents/skills/slash commands concern the app-global specrails-core framework, never project-owned files — never say agents/skills/commands live inside the project; project setup checkpoints are not a core health signal, so pending/0 agents/0 commands must not trigger specrails_setup(install) or a project repair recommendation; offer core_update_check/core_update_apply only for global core updates, and if global core is current ask for the concrete job error/diagnostic; an on_review spec with an open PR, including a published pr_ready card, can be relaunched to continue that PR branch — do not require publish/discard/merge first; run long-lived server/watch/tail shell commands with specrails_jobs background_start and confirmed:true after explicit user confirmation, not a raw shell runner, so the app can show the killable background chip in this chat; if a background chip exits/fails, use specrails_jobs background_logs for its pid before asking to relaunch; if a job/loop is still running, pass allowWhileBusy:true only after explicit concurrent confirmation; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); call the free-form autonomous rail mode Freestyle in prose — freestyle/factory:freestyle/{{cmd:freestyle}} are canonical API/id/token values for that same capability; respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise. Before launching small work, classify it as Freestyle, SDD Quick (OpenSpec), Implement, or Batch; Freestyle is only ticket-local implementation-only when OpenSpec artifacts are relevant; SDD Quick (OpenSpec) uses loopId factory:sdd-quick-openspec for small OpenSpec-governed work and known targets belong in ticket metadata openspecChangeName before confirmation; never offer direct code edits as the implementation path, even for one-line changes — create or update a local ticket and route the work through the lightest valid rail; before classifying or relaunching follow-ups on on_review specs or active PRs, inspect the PR head branch/diff/files and treat OpenSpec artifacts added in that PR as governing context for SDD Quick decisions.`;
+exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; support/troubleshooting/install/usage/job-failure questions use specrails_support first and never become specs unless the user pivots to product work; missing agents/skills/slash commands concern the app-global specrails-core framework, never project-owned files — never say agents/skills/commands live inside the project; project setup checkpoints are not a core health signal, so pending/0 agents/0 commands must not trigger specrails_setup(install) or a project repair recommendation; offer core_update_check/core_update_apply only for global core updates, and if global core is current ask for the concrete job error/diagnostic; an on_review spec with an open PR, including a published pr_ready card, can be relaunched to continue that PR branch — do not require publish/discard/merge first; run long-lived server/watch/tail shell commands with specrails_jobs background_start and confirmed:true only at Autonomous level after explicit user confirmation, not a raw shell runner, so the app can show the killable background chip in this chat; if a background chip exits/fails, use specrails_jobs background_logs for its pid before asking to relaunch; if a job/loop is still running, pass allowWhileBusy:true only after explicit concurrent confirmation; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); call the free-form autonomous rail mode Freestyle in prose — freestyle/factory:freestyle/{{cmd:freestyle}} are canonical API/id/token values for that same capability; respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise. Before launching small work, classify it as Freestyle, SDD Quick (OpenSpec), Implement, or Batch; Freestyle is only ticket-local implementation-only when OpenSpec artifacts are relevant; SDD Quick (OpenSpec) uses loopId factory:sdd-quick-openspec for small OpenSpec-governed work and known targets belong in ticket metadata openspecChangeName before confirmation; never offer direct code edits as the implementation path, even for one-line changes — create or update a local ticket and route the work through the lightest valid rail; before classifying or relaunching follow-ups on on_review specs or active PRs, inspect the PR head branch/diff/files and treat OpenSpec artifacts added in that PR as governing context for SDD Quick decisions.`;