specrails-desktop 2.64.1 → 2.65.0

package/server/dist/mcp/guide.js

@@ -197,7 +197,7 @@ heading inside the description); \`labels\`; \`priority\`. Spec content is Engli
     larger sets across several rails (they run in parallel) or sequential
     launches. There is no separate batch mode.
   - Freestyle: sends a free-form autonomous prompt to a capable provider — one
-    job per ticket; Claude and Kimi; \`model\` picker. Claude additionally
+    job per ticket; Claude, Codex, Gemini, Kimi and local engines; \`model\` picker. Claude additionally
     supports optional \`interactive\` in-job chat (settle with
     \`specrails_jobs(finalize)\`). To launch it through the API, pass the canonical mode value \`freestyle\`. In user-facing language, call
     the feature "Freestyle".
@@ -303,7 +303,7 @@ list/get/spending/watch = read; from_prompt, update, set_tickets,
 create_rail, plugin install, Jira connect = write; spec create/generate, rail
 launch/launch_all, chat send, job spawn = ai-spawn; spec delete, rail stop, job
 purge, plugin uninstall, Jira disconnect, project unregister = destructive.
-\`specrails_support(triage/core_update_status/core_update_check)\` is read;
+\`specrails_support(triage/core_update_status/core_update_check/api_meta)\` is read;
 \`specrails_support(core_update_apply)\` is ai-spawn because it runs longer
 global update work. Note the
 embedded spec-refinement happy path needs only read + write when using a fresh
@@ -314,7 +314,7 @@ can run Contract Refine require AI-spawn, including Explore conversions.
 
 - Installed providers are per-project; AI-spawning calls may pick any installed
   one (\`aiEngine\`); rails carry a per-rail engine.
-- Claude and Kimi support Freestyle mode (pass the canonical
+- Claude, Codex, Gemini, Kimi and local engines support Freestyle mode (pass the canonical
   API value \`freestyle\`; call the feature "Freestyle" to users). Persistent
   interactive jobs remain Claude-only.
 - Kimi prompt mode cannot enforce a no-tools or read-only boundary. Consequently
@@ -351,7 +351,10 @@ can run Contract Refine require AI-spawn, including Explore conversions.
   Truncated scans or skipped files do not prove that a symbol is absent.
 - **Run failures & recovery**: Start with \`specrails_jobs(runtime_diagnose, jobId)\`
   for original scope, completed steps, repeated failures and receipt validity.
-  Availability of Resume is not a repair recommendation. After the same failure,
+  Its \`reviewer\` field is the latest reviewer verdict of the run (approved,
+  score, bounded issues, summary lines, failing host checks and, for Flow →
+  Spec, derivation coverage with unexplained files); read it to explain why a
+  review said no — never present that as a hypothesis. Availability of Resume is not a repair recommendation. After the same failure,
   identify and validate a changed precondition before retrying; do not default
   to Relaunch. Evidence can be paged with evidenceId/section/sourceId/cursor/limit.
   \`specrails_jobs(runtime_runs, jobId)\` reads
@@ -382,6 +385,13 @@ can run Contract Refine require AI-spawn, including Explore conversions.
   economy. TWO budget knobs exist: \`specrails_analytics(budget_set,
   dailyBudgetUsd)\` is PER-PROJECT and pauses that project's queue when
   exceeded; \`specrails_settings(set, dailyBudgetUsd)\` is the APP-WIDE budget.
+  Both also take \`weeklyBudgetUsd\`, \`monthlyBudgetUsd\` and \`runCapUsd\` (a
+  per-run soft cap: the run pauses \`budget_paused\` when its own cost reaches it).
+  \`decision_times\` reports median/p90 time to decision and to merge per
+  project and loop; \`unknown\` counts missing instants, never zero durations.
+  \`loop_economics\` compares loops: delivered/merged/discarded, cost per
+  delivery (authoritative vs estimated), rounds, escaped defects
+  (\`metadata.regressionOf\` on bug tickets); nulls mean no data, not zero.
 - **Plugins** (\`specrails_plugins\`): per-project MCP integrations; \`preview\`
   the diff before \`install\`; a degraded plugin never blocks rail launches.
 - **Profiles** (\`specrails_agents\`): per-project agent chains; the baseline
@@ -404,9 +414,9 @@ can run Contract Refine require AI-spawn, including Explore conversions.
   a core problem and must not trigger \`specrails_setup(install)\`. If global
   core is stale, offer \`core_update_check\` + \`core_update_apply\`. If global
   core is current but a real job still reports missing core definitions, ask for
-  the job error/diagnostic and give the manual fallback for standalone/legacy
-  core installs: from the project root, run \`npx specrails-core@latest update\`,
-  then retry the job.
+  the job error/diagnostic and report a framework-loading bug. Core 6 has no
+  standalone \`update\` command: Core updates go through \`core_update_check\`
+  + \`core_update_apply\` (humans: Settings → Updates in the app).
 - **Loops lifecycle** (\`specrails_loops\`): Draft → \`publish\` (graph-validated)
   → runnable; \`update\` reverts to Draft and returns 409 while running;
   \`preview\` dry-runs token resolution without spawning; constants are shared

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

@@ -103,7 +103,7 @@ function agentsTools() {
                     .optional()
                     .describe('Explicit profile name to preview in `resolve` (omit to resolve the project default)'),
                 profile: zod_1.z
-                    .record(zod_1.z.unknown())
+                    .record(zod_1.z.string(), zod_1.z.unknown())
                     .optional()
                     .describe('Full Profile body for create/update: { schemaVersion:1, name, description?, provider?, orchestrator:{model}, agents:[], routing:[] }'),
                 windowDays: zod_1.z.number().int().optional().describe('analytics time window in days (1-365, default 30)'),

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

@@ -32,14 +32,16 @@ function analyticsTools() {
                 'ticket_summary (per-ticket cost aggregate across all surfaces), ' +
                 'export (download summary/raw analytics as CSV or JSON — file download, returns a note + headers), ' +
                 'budget_get (daily budget, per-job threshold, cost-today, utilization %), ' +
-                'budget_set (write — set/clear daily budget cap + per-job cost threshold; a too-low budget pauses the job queue). ' +
+                'budget_set (write — set/clear daily budget cap + per-job cost threshold; a too-low budget pauses the job queue), ' +
+                'decision_times (time to decision and time to merge per delivery: median/p90 ms per project and per loop, from when the delivery became reviewable; counts measured/pending/unknown — unknown is never zero; honours period/from/to only), ' +
+                'loop_economics (per loop over the period: delivered (reached on_review or beyond) / merged / discarded counts, discardRate, cost per delivery split authoritative vs estimated with unpriced deliveries excluded, decision times, review/fixer rounds per delivery from loop_step events, escapedDefects from tickets linked with metadata.regressionOf; requirementsDemonstrated {demonstrated,total,deliveries} sums the spec traces of delivered deliveries (Core specTrace) and is null when none carries one; triageAccuracy is null until its producer exists; hasData=false loops have no data — unknown is never zero; honours period/from/to only). ' +
                 'Prefer spending over invocations/export-raw for token economy. ' +
                 'Filters: period(7d|30d|90d|all|custom), from/to (ISO, required for custom), surface[], model[], modelProvider[] (index-aligned to model), provider[], status(success|failed|aborted), minCostUsd, ticketId, tzOffsetMinutes(±840 — pass the user local offset so "today" lines up), sortBy.',
             hintTier: 'read',
             tier: (a) => (a.action === 'budget_set' ? 'write' : 'read'),
             inputSchema: {
                 action: zod_1.z
-                    .enum(['spending', 'invocations', 'ticket_summary', 'export', 'budget_get', 'budget_set'])
+                    .enum(['spending', 'invocations', 'ticket_summary', 'export', 'budget_get', 'budget_set', 'decision_times', 'loop_economics'])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
                 // ─── Filters shared by spending / invocations / export ────────────────
@@ -97,6 +99,9 @@ function analyticsTools() {
                     .nullable()
                     .optional()
                     .describe('budget_set: per-job cost alert threshold USD (>0); null clears it'),
+                weeklyBudgetUsd: zod_1.z.number().nullable().optional().describe('budget_set: PER-PROJECT weekly cap USD (>0, week starts Monday local); null clears it. Enforced by the same gate as the daily budget.'),
+                monthlyBudgetUsd: zod_1.z.number().nullable().optional().describe('budget_set: PER-PROJECT monthly cap USD (>0, local calendar month); null clears it.'),
+                runCapUsd: zod_1.z.number().nullable().optional().describe('budget_set: per-run soft cap USD (>0): a loop run pauses (budget_paused) when its provider-reported cost reaches it and resumes after Continue/Raise. null clears it.'),
             },
             async handler(ctx, args) {
                 const base = (0, types_1.projectPath)(ctx, args.projectId);
@@ -118,6 +123,10 @@ function analyticsTools() {
                 switch (action) {
                     case 'spending':
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/spending${buildQuery(filters)}`);
+                    case 'decision_times':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/analytics/decision-times${buildQuery({ period: filters.period, from: filters.from, to: filters.to })}`);
+                    case 'loop_economics':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/analytics/loop-economics${buildQuery({ period: filters.period, from: filters.from, to: filters.to })}`);
                     case 'invocations':
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/invocations${buildQuery({
                             ...filters,
@@ -154,8 +163,11 @@ function analyticsTools() {
                             body.dailyBudgetUsd = args.dailyBudgetUsd;
                         if ('jobCostThresholdUsd' in args)
                             body.jobCostThresholdUsd = args.jobCostThresholdUsd;
+                        for (const field of ['weeklyBudgetUsd', 'monthlyBudgetUsd', 'runCapUsd'])
+                            if (field in args)
+                                body[field] = args[field];
                         if (Object.keys(body).length === 0) {
-                            throw new Error('budget_set requires dailyBudgetUsd and/or jobCostThresholdUsd (number>0 to set, null to clear).');
+                            throw new Error('budget_set requires dailyBudgetUsd, weeklyBudgetUsd, monthlyBudgetUsd, runCapUsd and/or jobCostThresholdUsd (number>0 to set, null to clear).');
                         }
                         return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/budget`, body);
                     }

package/server/dist/mcp/tools/app-settings.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.appTools = appTools;
 const zod_1 = require("zod");
 const desktop_db_1 = require("../../desktop-db");
+const budget_storage_1 = require("../../modules/execution/adapters/budget-storage");
 const mcp_tiers_1 = require("../mcp-tiers");
 const types_1 = require("./types");
 // App-level settings the MCP may read/write. NOTE: the MCP enable flag and the
@@ -43,6 +44,9 @@ function appTools() {
                     .nullable()
                     .optional()
                     .describe('APP-WIDE daily budget cap USD across all projects; null clears it. Per-project caps live in specrails_analytics(budget_set).'),
+                weeklyBudgetUsd: zod_1.z.number().min(0).nullable().optional().describe('APP-WIDE weekly cap USD across all projects (week starts Monday local); null clears it.'),
+                monthlyBudgetUsd: zod_1.z.number().min(0).nullable().optional().describe('APP-WIDE monthly cap USD across all projects (local calendar month); null clears it.'),
+                runCapUsd: zod_1.z.number().min(0).nullable().optional().describe('APP-WIDE default per-run soft cap USD: a loop run pauses when its provider-reported cost reaches it; null clears it.'),
                 costAlertThresholdUsd: zod_1.z.number().min(0).nullable().optional(),
                 projectId: zod_1.z.string().optional().describe('get: also report this project\'s "Allow sub-agents" setting'),
                 summaryLanguage: zod_1.z
@@ -81,6 +85,9 @@ function appTools() {
                         theme,
                         language: (0, desktop_db_1.getDesktopSetting)(db, 'ui_language') ?? null,
                         dailyBudgetUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'desktop_daily_budget_usd')),
+                        weeklyBudgetUsd: num((0, desktop_db_1.getDesktopSetting)(db, budget_storage_1.DESKTOP_CAP_KEYS.week)),
+                        monthlyBudgetUsd: num((0, desktop_db_1.getDesktopSetting)(db, budget_storage_1.DESKTOP_CAP_KEYS.month)),
+                        runCapUsd: num((0, desktop_db_1.getDesktopSetting)(db, budget_storage_1.DESKTOP_CAP_KEYS.run)),
                         costAlertThresholdUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'cost_alert_threshold_usd')),
                         // Code Explorer settings (same keys + defaults as GET /api/code-explorer-settings)
                         summaryLanguage: (0, desktop_db_1.getDesktopSetting)(db, 'summary_language') === 'es' ? 'es' : 'en',
@@ -112,6 +119,12 @@ function appTools() {
                     writeNumOrClear(db, 'desktop_daily_budget_usd', args.dailyBudgetUsd);
                     changed.push('dailyBudgetUsd');
                 }
+                for (const [field, key] of [['weeklyBudgetUsd', budget_storage_1.DESKTOP_CAP_KEYS.week], ['monthlyBudgetUsd', budget_storage_1.DESKTOP_CAP_KEYS.month], ['runCapUsd', budget_storage_1.DESKTOP_CAP_KEYS.run]]) {
+                    if (args[field] !== undefined) {
+                        writeNumOrClear(db, key, args[field]);
+                        changed.push(field);
+                    }
+                }
                 if (args.costAlertThresholdUsd !== undefined) {
                     writeNumOrClear(db, 'cost_alert_threshold_usd', args.costAlertThresholdUsd);
                     changed.push('costAlertThresholdUsd');
@@ -170,5 +183,5 @@ function writeNumOrClear(db, key, value) {
 }
 async function projectSubagentSettings(ctx, projectId) {
     const settings = (await (0, types_1.apiCall)(ctx, 'GET', `/projects/${encodeURIComponent(projectId)}/settings`));
-    return { projectAllowSubagents: settings.allowSubagents === true, projectSubagentRuntime: settings.subagentRuntime ?? null };
+    return { projectAllowSubagents: settings.allowSubagents !== false, projectSubagentRuntime: settings.subagentRuntime ?? null };
 }

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

@@ -62,7 +62,7 @@ function chatTools() {
                 provider: zod_1.z.string().optional().describe('AI engine for create — must be installed on the project (alias of aiEngine); defaults to the primary provider'),
                 model: zod_1.z.string().optional().describe('Model for create/update — must be valid for the conversation\'s provider'),
                 contextScope: zod_1.z
-                    .record(zod_1.z.unknown())
+                    .record(zod_1.z.string(), zod_1.z.unknown())
                     .optional()
                     .describe('Explore-only context scope flags for create: {full: repo-wide investigation, specrails: specs context, ' +
                     'openspec: openspec context, mcp: load project .mcp.json (spawns from repo cwd, slower), ' +

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

@@ -43,6 +43,7 @@ function envTools() {
             description: 'Read, scan, and configure the per-project environment variable NAME allowlist used for rail jobs and isolated loop worktrees. ' +
                 'Values are never read or stored by this tool; runs read them from the server environment and can recover configured names from the login shell when the desktop process is missing them. scan inspects safe repo config files such as package.json, .npmrc, .yarnrc.yml and pnpm-workspace.yaml for ${VAR} / process.env.VAR references and private scoped package auth hints. ' +
                 'Each configured name reports a value-free resolution status: inherited, recovered (from the login shell), not-defined, probe-timeout or probe-failed. ' +
+                'get also reports the project agentEnvMode (inherit | minimal); that mode is read-only here so an agent cannot widen its own environment. ' +
                 'Actions: get (read current names and their statuses), status (statuses only), recheck (probe the login shell now, then return statuses), scan (discover candidates), set (write names), auto_configure (scan then merge discovered names into settings).',
             hintTier: 'read',
             tier: (args) => (args.action === 'set' || args.action === 'auto_configure' ? 'write' : 'read'),
@@ -58,13 +59,14 @@ function envTools() {
                 if (action === 'get') {
                     const settings = await (0, types_1.apiCall)(ctx, 'GET', `${base}/settings`);
                     const names = Array.isArray(settings.worktreeEnvPassthrough) ? settings.worktreeEnvPassthrough : [];
+                    const agentEnvMode = settings.agentEnvMode === 'minimal' ? 'minimal' : 'inherit';
                     // Statuses are best-effort: an older server without the route still answers names.
                     try {
                         const { statuses } = sanitizeStatus(await (0, types_1.apiCall)(ctx, 'GET', `${base}/env-passthrough/status`));
-                        return { names, statuses };
+                        return { names, agentEnvMode, statuses };
                     }
                     catch {
-                        return { names };
+                        return { names, agentEnvMode };
                     }
                 }
                 if (action === 'status') {

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

@@ -1,10 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.activeFlowWorkspace = activeFlowWorkspace;
 exports.jobsTools = jobsTools;
 const zod_1 = require("zod");
 const types_1 = require("./types");
 const transient_children_1 = require("../../transient-children");
 const background_process_service_1 = require("../../modules/terminals/runtime/background-process-service");
+const app_urls_1 = require("../../modules/terminals/runtime/app-urls");
+const project_repositories_1 = require("../../project-repositories");
+const APP_URLS_HINT = 'appUrls are the addresses this process announced. Give the user each as a clickable markdown link: local opens on this computer; network opens from a phone or another device on the same Wi-Fi/VPN. No network URL means the server only listens on this computer (it was started without its host/LAN flag).';
+const FLOW_APP_HINT = 'Started in the Flow worktree. Read background_logs now for the listening URL or a startup failure, then give the user the appUrls as clickable links. The Flow bar shows Preview and Stop while it runs; Specrails stops it when the Flow is paused, discarded or handed off.';
+/**
+ * The ACTIVE Flow of the authenticated conversation in this project, through
+ * the project's Flow use cases (bound at composition). A paused or settling
+ * Flow, a missing Flow service or a failing lookup all mean "no Flow".
+ */
+function activeFlowWorkspace(projectCtx, conversationId) {
+    if (!conversationId)
+        return null;
+    try {
+        const flow = projectCtx.flow?.getByConversation(conversationId);
+        if (!flow || flow.state !== 'active' || flow.step !== null || !flow.worktreePath)
+            return null;
+        // `repositoryId`: the non-primary repository the Flow runs in (absent ⇒ primary).
+        return { flowId: flow.id, worktreePath: flow.worktreePath, ...(flow.repositoryId ? { repositoryId: flow.repositoryId } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Entering Flow already granted write and execution in the Flow worktree, so
+ * inside an ACTIVE Flow the in-app agent may start (with the user's explicit
+ * confirmation) and stop that Flow's background processes below the
+ * Autonomous level. Everything else keeps the ladder.
+ */
+function flowBackgroundException(ctx, args) {
+    const action = args.action;
+    if (action !== 'background_start' && action !== 'background_kill')
+        return false;
+    if (action === 'background_start' && args.confirmed !== true)
+        return false;
+    let projectCtx;
+    try {
+        projectCtx = (0, types_1.requireProject)(ctx, args.projectId);
+    }
+    catch {
+        return false;
+    }
+    const flow = activeFlowWorkspace(projectCtx, ctx.originConversationId);
+    if (!flow)
+        return false;
+    if (action === 'background_start')
+        return true;
+    const pid = args.pid;
+    if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    const process = (0, transient_children_1.getBackgroundProcess)(pid, typeof args.processId === 'string' ? args.processId : undefined);
+    return process?.flowId === flow.flowId && process.projectId === projectCtx.project.id && process.chatId === ctx.originConversationId;
+}
 function requireFirstPartyConversation(ctx, action) {
     if (!ctx.firstPartyAgent || !ctx.originConversationId) {
         throw new Error(`${action} is available only to an authenticated in-app agent turn.`);
@@ -28,7 +82,7 @@ function jobsTools() {
             title: 'Jobs & Queue',
             description: 'Manage a project\'s AI-pipeline job queue and individual jobs. ' +
                 'Actions: list, get, queue, spawn (ai-spawn — enqueues a direct slash-command job in the primary repository only, returns {jobId,position}, async; repositoryId is required for multi-repository projects; use specrails_rails launch for spec implementations or specrails_loops run for coordinated secondary/multi-repository work; from the in-app agent chat the engine defaults to your conversation\'s provider — pass aiEngine to override), ' +
-                'background_start (in-app-agent-only destructive shell command tied to the authenticated chat; requires confirmed:true after explicit user confirmation), background_list (read scoped running/recent applications), background_logs (read bounded stdout/stderr and actual lifecycle), background_kill (in-app-agent-only destructive; stopping is not yet stopped), ' +
+                'background_start (in-app-agent-only destructive shell command tied to the authenticated chat; requires confirmed:true after explicit user confirmation; inside an active Flow it runs in the Flow worktree, is tagged with the Flow and is allowed below the Autonomous level), background_list (read scoped running/recent applications), background_logs (read bounded stdout/stderr and actual lifecycle), background_kill (in-app-agent-only destructive; stopping is not yet stopped; a Flow\'s own processes can be stopped from that Flow below the Autonomous level), ' +
                 'cancel (destructive — requests cancellation of a running/queued job; it does not delete terminal history), ' +
                 'purge (destructive — bulk-delete persisted job rows in a date range), ' +
                 'pause / resume (queue), reorder (queued-job order), priority (change a queued job\'s priority), ' +
@@ -39,14 +93,15 @@ function jobsTools() {
                 'interactive_turn (ai-spawn — send a steering prompt to any running interactive job; claude jobs are interactive by default), ' +
                 'finalize (settle a running interactive job now — Freestyle jobs otherwise wait for it, others auto-settle), ' +
                 'runtime_runs (read the programmatic runtime state of jobId — or every run when omitted — status, nextStep, canResume, recoverableSteps, pendingApproval, pendingQuestion; THIS is how you learn why a run failed and what recovery it offers), ' +
-                'runtime_diagnose (read-only recovery assessment for jobId: original scope, completed steps, repeated failures and verification invalidation reasons; use before recommending retry or relaunch), ' +
-                'runtime_evidence (read the durable runtime evidence of jobId; page with evidenceId/section/sourceId/cursor/limit), ' +
+                'runtime_diagnose (read-only recovery assessment for jobId: original scope, completed steps, repeated failures, verification invalidation reasons and `reviewer` — the latest reviewer verdict: approved, score, issues, summary, failing host checks, Flow → Spec derivation coverage; use before recommending retry or relaunch and to explain a rejected review), ' +
+                'runtime_evidence (read the durable runtime evidence of jobId; the overview page also carries `reviewer`; page with evidenceId/section/sourceId/cursor/limit), ' +
                 'runtime_steer (write — queue steeringText in an engine v2 run with a stable requestId; acceptance is not consumption; inspect runtime_runs steering receipts), ' +
                 'runtime_resume (ai-spawn — continue a resumable run: optional approve/recover/invalidate step-id lists + answer for a pending question; act ONLY after the user confirmed on the card), ' +
                 'runtime_recover (ai-spawn — shorthand for runtime_resume with recover:[stepIds] over the recoverable steps), ' +
                 'runtime_approve (write — shorthand for runtime_resume with approve:[stepId] for a pending approval), ' +
                 'runtime_settle (write — prepare delivery for a succeeded-but-unsettled run), runtime_dismiss (write — dismiss a settled continuation from the rail card), ' +
-                'runtime_cancel (destructive — cancel an active runtime continuation).',
+                'runtime_cancel (destructive — cancel an active runtime continuation), ' +
+                'audit (read — what the agents of jobId read, wrote, executed, called over MCP or fetched, as JSONL or CSV via format; omit jobId for a project-wide export bounded by from/to; reads are only as complete as each provider\'s stream).',
             hintTier: 'read',
             tier: (a) => {
                 const action = a.action;
@@ -58,6 +113,7 @@ function jobsTools() {
                     return 'write';
                 return 'read';
             },
+            tierException: flowBackgroundException,
             inputSchema: {
                 action: zod_1.z
                     .enum([
@@ -97,6 +153,7 @@ function jobsTools() {
                     'runtime_settle',
                     'runtime_dismiss',
                     'runtime_cancel',
+                    'audit',
                 ])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
@@ -138,14 +195,14 @@ function jobsTools() {
                 text: zod_1.z.string().optional().describe('Prompt text for interactive_turn'),
                 chatId: zod_1.z.string().optional().describe('Conversation id for background_logs ownership. background_start/background_kill ignore this field and use the authenticated in-app capability.'),
                 repositoryId: zod_1.z.string().min(1).optional().describe('spawn/background_start: repository membership ID; required when the project has several repositories. spawn accepts only the primary repository; use specrails_rails launch or specrails_loops run for other repositories.'),
-                cwd: zod_1.z.string().optional().describe('Optional cwd for background_start; resolved inside the selected repository root. For tests/dev servers, discover workspacePaths with specrails_projects get and pass the intended code workspace cwd explicitly'),
+                cwd: zod_1.z.string().optional().describe('Optional cwd for background_start; resolved inside the selected repository root (inside an active Flow: inside the Flow worktree, and repositoryId is ignored). For tests/dev servers, discover workspacePaths with specrails_projects get and pass the intended code workspace cwd explicitly'),
                 pid: zod_1.z.number().int().positive().optional().describe('Background process pid for background_logs/background_kill'),
                 processId: zod_1.z.string().min(1).max(200).optional().describe('Background execution UUID returned by background_start/list. Pass with pid on logs/kill to avoid targeting a reused PID.'),
                 includeFinished: zod_1.z.boolean().optional().describe('background_list: include persisted completed/disconnected executions (default true). Active applications are listed first; use limit/offset for older history.'),
                 confirmed: zod_1.z.boolean().optional().describe('background_start only: must be true after explicit user confirmation for this exact command'),
                 allowWhileBusy: zod_1.z.boolean().optional().describe('background_start only: override active job/loop guard after explicit user confirmation'),
                 // ── export ──
-                format: zod_1.z.enum(['json', 'csv']).optional().describe('Export format (default json)'),
+                format: zod_1.z.enum(['json', 'csv', 'jsonl']).optional().describe('Export format: export json|csv (default json); audit jsonl|csv (default jsonl)'),
                 // ── default_spec_model ──
                 provider: zod_1.z.string().optional().describe('Provider to resolve the default spec model for (default_spec_model)'),
                 // ── runtime_* (mission-rail-cards: the agent's eyes + hands on a failed run) ──
@@ -272,6 +329,23 @@ function jobsTools() {
                         const qs = new URLSearchParams({ jobIds: jobIds.join(',') });
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/jobs/compare?${qs.toString()}`);
                     }
+                    case 'audit': {
+                        const format = args.format === 'csv' ? 'csv' : 'jsonl';
+                        const qs = new URLSearchParams({ format });
+                        const id = args.jobId;
+                        if (!id) {
+                            if (args.from)
+                                qs.set('from', args.from);
+                            if (args.to)
+                                qs.set('to', args.to);
+                        }
+                        const path = id ? `${base}/jobs/${encodeURIComponent(id)}/audit?${qs.toString()}` : `${base}/agent-actions?${qs.toString()}`;
+                        const raw = await (0, types_1.apiCall)(ctx, 'GET', path);
+                        // The loopback client parses a single JSONL line as JSON; keep the export textual.
+                        const data = typeof raw === 'string' ? raw : raw == null ? '' : `${JSON.stringify(raw)}\n`;
+                        const rows = data ? data.split('\n').filter(Boolean).length - (format === 'csv' ? 1 : 0) : 0;
+                        return { format, ...(id ? { jobId: id } : {}), rows, note: 'Reads are only as complete as each provider stream reports them.', data };
+                    }
                     case 'export': {
                         const qs = new URLSearchParams();
                         qs.set('format', args.format ?? 'json');
@@ -447,6 +521,19 @@ function jobsTools() {
                             throw new Error('background_start requires confirmed:true after explicit user confirmation for this exact command.');
                         const chatId = requireFirstPartyConversation(ctx, 'background_start');
                         const projectCtx = (0, types_1.requireProject)(ctx, args.projectId);
+                        // Inside an active Flow the app runs in the Flow worktree (never the
+                        // project checkout), tagged with the Flow so it stops with it. The
+                        // worktree is isolated, so the project's busy guard does not apply.
+                        const flow = activeFlowWorkspace(projectCtx, chatId);
+                        if (flow) {
+                            const cwd = (0, background_process_service_1.resolveBackgroundCwd)(flow.worktreePath, args.cwd, 'the Flow worktree');
+                            const repository = flow.repositoryId ? (0, project_repositories_1.getProjectRepositories)(projectCtx.project).find((member) => member.id === flow.repositoryId) : undefined;
+                            const process = (0, transient_children_1.startBackgroundProcess)(command.trim(), cwd, chatId.trim(), projectCtx.project.id, (0, background_process_service_1.backgroundProcessHooks)(ctx.broadcast), { flowId: flow.flowId, ...(repository ? { repositoryId: repository.id, repositoryName: repository.name } : {}) });
+                            return { ok: true, flowId: flow.flowId, cwd, process, hint: FLOW_APP_HINT };
+                        }
+                        // The Flow exception admitted this call, but the Flow ended meanwhile.
+                        if (ctx.agentTierLevel !== undefined && !(0, types_1.toolTierAllowed)(ctx, 'destructive'))
+                            throw new Error('The Flow is no longer active, so background_start needs the Autonomous permission level again.');
                         const busyReason = (0, background_process_service_1.backgroundStartBusyReason)(projectCtx);
                         if (busyReason && args.allowWhileBusy !== true) {
                             throw new Error(`background_start refused because ${busyReason}. Wait for it to finish, or pass allowWhileBusy:true only after explicit user confirmation.`);
@@ -467,7 +554,7 @@ function jobsTools() {
                             .sort((a, b) => Number(terminal.has(a.status)) - Number(terminal.has(b.status)) || b.startedAt - a.startedAt);
                         const limit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? Math.min(200, Math.max(1, Math.floor(args.limit))) : 50;
                         const offset = typeof args.offset === 'number' && Number.isFinite(args.offset) ? Math.max(0, Math.floor(args.offset)) : 0;
-                        return { processes: processes.slice(offset, offset + limit), total: processes.length, offset, limit, hasMore: offset + limit < processes.length,
+                        return { processes: processes.slice(offset, offset + limit).map(app_urls_1.withAppUrls), total: processes.length, offset, limit, hasMore: offset + limit < processes.length,
                             ...(Number.isSafeInteger(ctx.desktopPort) && ctx.desktopPort > 0 ? { specrailsApi: { host: '127.0.0.1', port: ctx.desktopPort } } : {}),
                             hint: 'History includes persisted executions. interrupted means supervision ended after restart; current OS state is unknown and the historical PID cannot be signalled. Keep application ports separate from the Specrails API. Inspect persisted failure logs before proposing another launch.' };
                     }
@@ -508,9 +595,11 @@ function jobsTools() {
                         });
                         if (!logs)
                             throw new Error('background_logs requires a registered pid in the same project/chat; logs may have expired.');
+                        const { appUrls } = (0, app_urls_1.withAppUrls)(logs.process);
                         return {
                             ok: true,
                             ...logs,
+                            ...(appUrls ? { appUrls, appUrlsHint: APP_URLS_HINT } : {}),
                             hint: logs.lines.length > 0
                                 ? 'Inspect stdout/stderr to explain why the background process exited or failed.'
                                 : 'No stdout/stderr output has been captured yet. Check the returned process status; empty logs do not prove application readiness.',

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

@@ -117,7 +117,7 @@ function loopsTools() {
                     .describe('Loop or constant name (required for create / constant_create; optional override for from_template / fork / duplicate / update)'),
                 description: zod_1.z.string().optional().describe('Loop description (for create / update)'),
                 graph: zod_1.z
-                    .record(zod_1.z.unknown())
+                    .record(zod_1.z.string(), zod_1.z.unknown())
                     .optional()
                     .describe('Loop graph object { nodes, edges, ... } (for create / update; required for preview)'),
                 value: zod_1.z.string().optional().describe('Constant value (for constant_create / constant_update)'),

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

@@ -6,12 +6,11 @@ const project_repositories_1 = require("../../project-repositories");
 const zod_json_schema_compat_js_1 = require("@modelcontextprotocol/sdk/server/zod-json-schema-compat.js");
 const guide_1 = require("../guide");
 const types_1 = require("./types");
-/**
- * Serialize a raw-shape zod field into `{ name, description, type, enumValues?,
- * optional }`. Unwraps optional/default/nullable wrappers (keeping the OUTERMOST
- * `.describe()` string, the convention across the tool files) down to the base
- * type so the model sees the real type + enum values instead of a bare key name.
- */
+/** Lower-case kind of a zod schema: zod 3 exposes `_def.typeName` ('ZodOptional'), zod 4 `_def.type` ('optional'). */
+function zodKind(schema) {
+    const def = schema._def;
+    return (def?.typeName?.replace(/^Zod/, '') ?? def?.type ?? 'unknown').toLowerCase();
+}
 function describeZodField(name, field) {
     let current = field;
     let optional = false;
@@ -21,22 +20,20 @@ function describeZodField(name, field) {
         if (description === undefined && current.description !== undefined)
             description = current.description;
         const def = current._def;
-        const typeName = def?.typeName;
-        if ((typeName === 'ZodOptional' || typeName === 'ZodDefault') && def?.innerType) {
+        const kind = zodKind(current);
+        if ((kind === 'optional' || kind === 'default') && def?.innerType) {
             optional = true;
             current = def.innerType;
             continue;
         }
-        if (typeName === 'ZodNullable' && def?.innerType) {
+        if (kind === 'nullable' && def?.innerType) {
             nullable = true;
             current = def.innerType;
             continue;
         }
         break;
     }
-    const baseName = (current._def?.typeName ?? 'ZodUnknown')
-        .replace(/^Zod/, '')
-        .toLowerCase();
+    const baseName = zodKind(current);
     const type = nullable ? `${baseName} | null` : baseName;
     const out = { name, type, optional };
     if (description !== undefined)
@@ -123,7 +120,7 @@ function metaTools(getSpecs) {
             tier: 'read',
             inputSchema: {
                 name: zod_1.z.string().describe('Tool name, e.g. "specrails_rails"'),
-                arguments: zod_1.z.record(zod_1.z.unknown()).optional().describe('Optional prospective tool arguments to validate and preview permissions; never executes the tool'),
+                arguments: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('Optional prospective tool arguments to validate and preview permissions; never executes the tool'),
             },
             handler: (ctx, args) => {
                 const name = String(args.name ?? '');

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

@@ -43,6 +43,8 @@ function railsTools() {
                 'Actions: list (rails + active jobs/loop runs; every rail carries availability free|busy|pending_decision|on_review — prefer a free rail when proposing a launch card, else create_rail), pr_candidates (read compatible open PR targets for railIndex), review_packet (read durable evidence, verification and acceptance capability by prDeliveryId), create_rail (add a new rail slot; returns its railIndex), set_tickets (assign ticket IDs), set_profile (default agent profile, null=legacy), ' +
                 'set_engine (provider override, null=primary), set_name (display label, null clears), ' +
                 'launch (ai-spawn — spawns the selected installed provider CLI job(s), including Kimi when installed, that WRITE CODE, RUN TESTS, COMMIT, and INCUR TOKEN COST; returns 202 with jobId/jobIds/loopRunIds), ' +
+                'launch and launch_all are refused with 409 daily_budget_exceeded (scope project|desktop, budgetUsd, spentUsd, resetsAt) while a daily budget is exhausted — nothing spawns; tell the user to raise the budget or wait for the reset, never retry in a loop. ' +
+                'They are also refused with 409 review_wip_limit_reached (limit, pending[{ deliveryId, railIndex, ticketIds, since }]) when the project\'s review limit of deliveries waiting for review is reached — nothing spawns; continuations of an existing delivery (revision, relaunch, PR follow-up) are exempt. Tell the user which deliveries are waiting and that deciding one (Create PR, merge, discard) or raising the limit in Project settings frees a slot; never retry in a loop. list returns reviewWip { limit, pending, reached }. ' +
                 'launch_all (ai-spawn — launches EVERY rail that has tickets and no active run/uncontinuable pending PR decision, in parallel, using each rail\'s stored mode/engine/profile; returns per-rail outcomes with skip reasons), ' +
                 'stop (destructive — kills all active jobs and loop runs for the rail). ' +
                 'For on_review tickets with an already-open GitHub PR (including a published pr_ready delivery), launch automatically tries to continue that PR head branch; Jira-linked in_progress tickets can do the same when the PR match is explicit; fresh tickets still start from the project integration branch. ' +
@@ -104,7 +106,7 @@ function railsTools() {
                 mode: zod_1.z
                     .enum(['implement', 'freestyle', 'loop'])
                     .optional()
-                    .describe('Launch mode (launch; default "implement"). Implement runs all of the rail\'s tickets in one aggregate run; propose at most 3 specs per rail and split larger sets across rails. Use "freestyle" as the canonical API enum value for Freestyle. It invokes the selected provider\'s native free-form autonomous workflow (currently Claude and Kimi), one job per ticket. In prose, call it "Freestyle". Loop runs an app-driven loop per ticket.'),
+                    .describe('Launch mode (launch; default "implement"). Implement runs all of the rail\'s tickets in one aggregate run; propose at most 3 specs per rail and split larger sets across rails. Use "freestyle" as the canonical API enum value for Freestyle. It invokes the selected provider\'s native free-form autonomous workflow (Claude, Codex, Gemini, Kimi and local engines; only Claude is interactive), one job per ticket. In prose, call it "Freestyle". Loop runs an app-driven loop per ticket.'),
                 model: zod_1.z
                     .string()
                     .optional()
@@ -409,6 +411,18 @@ function railsTools() {
                                 else if (err instanceof types_1.McpApiError && err.status === 409 && err.code === 'tickets_in_flight') {
                                     results.push({ railIndex: idx, outcome: 'skipped', reason: 'tickets-in-flight', ticketIds });
                                 }
+                                else if (err instanceof types_1.McpApiError && err.status === 409 && err.code === 'daily_budget_exceeded') {
+                                    // Nothing spawned: the project or app-wide daily budget is exhausted.
+                                    const budget = err.data;
+                                    results.push({ railIndex: idx, outcome: 'skipped', reason: 'daily-budget-exceeded', ticketIds,
+                                        ...(typeof budget?.detail === 'string' ? { error: [budget.detail, budget.action].filter(v => typeof v === 'string').join(' ') } : {}) });
+                                }
+                                else if (err instanceof types_1.McpApiError && err.status === 409 && err.code === 'review_wip_limit_reached') {
+                                    // Nothing spawned: the project's review WIP limit is reached.
+                                    const wip = err.data;
+                                    results.push({ railIndex: idx, outcome: 'skipped', reason: 'review-wip-limit', ticketIds,
+                                        ...(typeof wip?.detail === 'string' ? { error: [wip.detail, wip.action].filter(v => typeof v === 'string').join(' ') } : {}) });
+                                }
                                 else {
                                     results.push({ railIndex: idx, outcome: 'failed', ticketIds, error: message });
                                 }

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

@@ -92,7 +92,7 @@ function setupTools() {
                 repositories: zod_1.z.array(zod_1.z.object({ path: zod_1.z.string().min(1), name: zod_1.z.string().optional(), workspacePaths: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).optional(), integrationBranch: zod_1.z.string().nullable().optional() })).max(50).optional().describe('add_project: additional repository memberships with their code workspaces'),
                 // install_config
                 config: zod_1.z
-                    .record(zod_1.z.unknown())
+                    .record(zod_1.z.string(), zod_1.z.unknown())
                     .optional()
                     .describe('install_config: the install-config object to serialize (e.g. { tier:"quick", provider, agents }); required for install_config'),
             },

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

@@ -13,7 +13,7 @@ const AI_SPAWN_ACTIONS = new Set(['create', 'generate', 'ai_edit', 'contract_ref
 // using its actual side effects, not the synchronous HTTP response alone.
 const WRITE_ACTIONS = new Set([
     'update', 'from_prompt', 'save_draft', 'commit_draft', 'cancel_ai_edit',
-    'add_addendum', 'update_addendum', 'dismiss_addendum', 'reopen_addendum',
+    'add_addendum', 'update_addendum', 'dismiss_addendum', 'reopen_addendum', 'restore',
 ]);
 function resolveSpecsTier(action, args) {
     if (action === 'commit_draft') {
@@ -47,7 +47,7 @@ function specsTools() {
             description: 'Manage the spec/ticket backlog for a project (the local-tickets.json store). ' +
                 'Actions: list, get, ' +
                 'create (ai-spawn — THE way to add a spec: routes through Quick Add Spec, so the specrails agent generates a structured spec with AI from the user request, exactly matching the app\'s "Add Spec → Quick" flow; pass the request as title/description, it becomes the idea; async), ' +
-                'update, delete (destructive), ' +
+                'update, delete (destructive; a soft delete: the spec moves to Recently deleted for 30 days), restore (write; bring a deleted spec back), ' +
                 'from_prompt (verbatim insert, no AI — use ONLY when you already have a complete finished spec to store as-is; ' +
                 'cannot set acceptanceCriteria or shortSummary — prefer commit_draft for structured specs), ' +
                 'save_draft (persist an Explore conversation as a draft), ' +
@@ -84,6 +84,7 @@ function specsTools() {
                     'create',
                     'update',
                     'delete',
+                    'restore',
                     'from_prompt',
                     'save_draft',
                     'commit_draft',
@@ -114,7 +115,7 @@ function specsTools() {
                     .number()
                     .int()
                     .optional()
-                    .describe('Numeric ticket id (get/update/delete/contract_refine/smash/smash_undo/delete_epic_children/spending_summary/files_touched/ai_edit/list_addenda/add_addendum/update_addendum/dismiss_addendum/reopen_addendum/delete_addendum)'),
+                    .describe('Numeric ticket id (get/update/delete/restore/contract_refine/smash/smash_undo/delete_epic_children/spending_summary/files_touched/ai_edit/list_addenda/add_addendum/update_addendum/dismiss_addendum/reopen_addendum/delete_addendum)'),
                 // ── list filters ─────────────────────────────────────────────────
                 status: zod_1.z
                     .string()
@@ -138,7 +139,7 @@ function specsTools() {
                 labels: zod_1.z.array(zod_1.z.string()).optional().describe('update/from_prompt/save_draft/commit_draft: labels array'),
                 assignee: zod_1.z.string().nullable().optional().describe('update/commit_draft: assignee; null clears'),
                 prerequisites: zod_1.z.array(zod_1.z.number().int()).optional().describe('update/commit_draft: prerequisite ticket ids'),
-                metadata: zod_1.z.record(zod_1.z.unknown()).optional().describe('update/commit_draft: free-form metadata object (update merges keys)'),
+                metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional().describe('update/commit_draft: free-form metadata object (update merges keys). regressionOf: delivery id that introduced this bug (escaped defect, loop_economics); null clears'),
                 acceptanceCriteria: zod_1.z
                     .array(zod_1.z.string())
                     .optional()
@@ -166,7 +167,7 @@ function specsTools() {
                     .optional()
                     .describe('create/generate/contract_refine: provider/engine override (must be installed; contract_refine cannot switch an Explore-origin provider)'),
                 contextScope: zod_1.z
-                    .record(zod_1.z.unknown())
+                    .record(zod_1.z.string(), zod_1.z.unknown())
                     .optional()
                     .describe('create/generate: context-awareness flags {specrails,openspec,full,mcp,userMcp,contractRefine}'),
                 contractRefine: zod_1.z
@@ -462,6 +463,8 @@ function specsTools() {
                     // ── destructive ────────────────────────────────────────────────
                     case 'delete':
                         return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/tickets/${requireId()}`);
+                    case 'restore':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/tickets/${requireId()}/restore`);
                     case 'smash_undo': {
                         if (!args.smashedAt)
                             throw new Error('smash_undo requires the "smashedAt" timestamp.');