specrails-desktop 2.64.2 → 2.65.0

package/server/dist/modules/execution/domain/agent-env.js

@@ -0,0 +1,98 @@
+"use strict";
+// Agent process environment policy (pure). Decides which variables of the
+// Desktop server environment reach an agent process. `inherit` keeps today's
+// behavior; `minimal` forwards only an allowlist, the project's passthrough
+// names, Specrails' own variables and the provider's declared auth/config
+// names. Values are never logged or persisted by this module.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_ENV_SPECRAILS_ALLOWLIST = exports.AGENT_ENV_WINDOWS_ALLOWLIST = exports.AGENT_ENV_BASE_ALLOWLIST = void 0;
+exports.matchesEnvPattern = matchesEnvPattern;
+exports.agentEnvAllowlist = agentEnvAllowlist;
+exports.minimalAgentEnvNames = minimalAgentEnvNames;
+exports.buildAgentEnv = buildAgentEnv;
+/** Names every agent process needs to start, find tools, reach a proxy and
+ *  format text. `*` at the end of an entry matches a name prefix. */
+exports.AGENT_ENV_BASE_ALLOWLIST = [
+    'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL',
+    'LANG', 'LANGUAGE', 'LC_*',
+    'TMPDIR', 'TMP', 'TEMP',
+    'TERM', 'COLORTERM', 'TZ',
+    'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_STATE_HOME', 'XDG_RUNTIME_DIR',
+    'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'ALL_PROXY',
+    'http_proxy', 'https_proxy', 'no_proxy', 'all_proxy',
+    'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
+];
+/** Windows names without which `cmd.exe`, npm/npx and most CLIs fail. Matched
+ *  case-insensitively on Windows; absent elsewhere. `windowsSpawnEnv` still
+ *  backfills the canonical values at spawn time. */
+exports.AGENT_ENV_WINDOWS_ALLOWLIST = [
+    'SystemRoot', 'SystemDrive', 'windir', 'ComSpec', 'PATHEXT',
+    'USERPROFILE', 'USERNAME', 'USERDOMAIN', 'HOMEDRIVE', 'HOMEPATH',
+    'APPDATA', 'LOCALAPPDATA', 'ProgramData', 'ALLUSERSPROFILE', 'PUBLIC',
+    'ProgramFiles', 'ProgramFiles(x86)', 'ProgramW6432',
+    'CommonProgramFiles', 'CommonProgramFiles(x86)', 'CommonProgramW6432',
+    'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE', 'PROCESSOR_IDENTIFIER',
+    'OS', 'COMPUTERNAME',
+];
+/** Specrails' own control-plane and bundled-runtime variables. */
+exports.AGENT_ENV_SPECRAILS_ALLOWLIST = ['SPECRAILS_*'];
+/** True when `name` matches `pattern` (`FOO` exact, `FOO_*` prefix). */
+function matchesEnvPattern(name, pattern, caseInsensitive = false) {
+    const n = caseInsensitive ? name.toUpperCase() : name;
+    const p = caseInsensitive ? pattern.toUpperCase() : pattern;
+    return p.endsWith('*') ? n.startsWith(p.slice(0, -1)) : n === p;
+}
+/** Every allowlist pattern that applies to one spawn, in a stable order. */
+function agentEnvAllowlist(providerAllowlist = []) {
+    return [...new Set([
+            ...exports.AGENT_ENV_BASE_ALLOWLIST,
+            ...exports.AGENT_ENV_WINDOWS_ALLOWLIST,
+            ...exports.AGENT_ENV_SPECRAILS_ALLOWLIST,
+            ...providerAllowlist,
+        ])];
+}
+/** Names of `sourceEnv` (plus passthrough names) the minimal mode would pass. */
+function minimalAgentEnvNames(input) {
+    const caseInsensitive = (input.platform ?? process.platform) === 'win32';
+    const patterns = agentEnvAllowlist(input.providerAllowlist);
+    const names = new Set();
+    for (const [name, value] of Object.entries(input.sourceEnv)) {
+        if (value === undefined)
+            continue;
+        if (patterns.some(pattern => matchesEnvPattern(name, pattern, caseInsensitive)))
+            names.add(name);
+    }
+    for (const [name, value] of Object.entries(input.passthrough)) {
+        if (value !== undefined)
+            names.add(name);
+    }
+    return [...names].sort();
+}
+/**
+ * Build the base environment of an agent process. Specrails' per-spawn
+ * overlays (telemetry, profile, repo map, relocation, provider overrides) are
+ * applied by callers on top of this result.
+ *
+ * - `inherit`: byte-identical to today: the source, with the passthrough overlay
+ *   only when it carries values (same object when it does not).
+ * - `minimal`: a fresh object with allowlisted names from the source, then the
+ *   passthrough values.
+ */
+function buildAgentEnv(input) {
+    if (input.mode !== 'minimal') {
+        return Object.keys(input.passthrough).length === 0
+            ? input.sourceEnv
+            : { ...input.sourceEnv, ...input.passthrough };
+    }
+    const allowed = new Set(minimalAgentEnvNames(input));
+    const out = {};
+    for (const [name, value] of Object.entries(input.sourceEnv)) {
+        if (value !== undefined && allowed.has(name))
+            out[name] = value;
+    }
+    for (const [name, value] of Object.entries(input.passthrough)) {
+        if (value !== undefined)
+            out[name] = value;
+    }
+    return out;
+}

package/server/dist/modules/execution/domain/daily-budget.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localDayStartIso = localDayStartIso;
+exports.dailyBudgetResetsAt = dailyBudgetResetsAt;
+exports.isDailyBudgetExceeded = isDailyBudgetExceeded;
+exports.dailyBudgetRejection = dailyBudgetRejection;
+/** Local calendar-day start as a UTC ISO instant (comparable to `started_at`). */
+function localDayStartIso(now) {
+    return new Date(now.getFullYear(), now.getMonth(), now.getDate()).toISOString();
+}
+/**
+ * The project budget sums the user's LOCAL day; the app-wide budget sums the
+ * UTC day (`date('now')`). Each scope reports the boundary it actually uses.
+ */
+function dailyBudgetResetsAt(scope, now) {
+    return scope === 'project'
+        ? new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1).toISOString()
+        : new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1)).toISOString();
+}
+function isDailyBudgetExceeded(snapshot) {
+    return snapshot?.budget != null && snapshot.budget > 0 && snapshot.totalSpend >= snapshot.budget;
+}
+function dailyBudgetRejection(breach, now) {
+    const label = breach.scope === 'project' ? 'project' : 'app-wide';
+    return {
+        error: 'daily_budget_exceeded',
+        scope: breach.scope,
+        budgetUsd: breach.budget,
+        spentUsd: breach.totalSpend,
+        resetsAt: dailyBudgetResetsAt(breach.scope, now),
+        detail: `Today's spend $${breach.totalSpend.toFixed(2)} has reached the ${label} daily budget of $${breach.budget.toFixed(2)}.`,
+        action: breach.scope === 'project'
+            ? 'Raise or clear the project daily budget (Project settings ▸ Budget), or wait for the daily reset.'
+            : 'Raise or clear the app-wide daily budget (Settings ▸ Budget), or wait for the daily reset.',
+    };
+}

package/server/dist/modules/execution/domain/spend-caps.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRAILING_DAYS = exports.isRunCapCrossed = exports.capHeadroomCents = exports.periodResetsAtIso = exports.periodStartIso = exports.fromCents = exports.toCents = exports.CAP_PERIODS = void 0;
+exports.periodStart = periodStart;
+exports.periodEnd = periodEnd;
+exports.isCapExceeded = isCapExceeded;
+exports.tightestCap = tightestCap;
+exports.firstExhaustedCap = firstExhaustedCap;
+exports.capRejection = capRejection;
+exports.runCapRejection = runCapRejection;
+exports.effectiveRunCap = effectiveRunCap;
+exports.localDayKey = localDayKey;
+exports.projectMonthEnd = projectMonthEnd;
+exports.CAP_PERIODS = ['day', 'week', 'month'];
+const toCents = (usd) => Math.round(usd * 100);
+exports.toCents = toCents;
+const fromCents = (cents) => cents / 100;
+exports.fromCents = fromCents;
+/** First instant of the period containing `now`, in local time. */
+function periodStart(period, now) {
+    if (period === 'day')
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    if (period === 'week') {
+        // Monday = 0 … Sunday = 6
+        const sinceMonday = (now.getDay() + 6) % 7;
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate() - sinceMonday);
+    }
+    return new Date(now.getFullYear(), now.getMonth(), 1);
+}
+/** First instant of the NEXT period (the reset), in local time. */
+function periodEnd(period, now) {
+    const start = periodStart(period, now);
+    if (period === 'day')
+        return new Date(start.getFullYear(), start.getMonth(), start.getDate() + 1);
+    if (period === 'week')
+        return new Date(start.getFullYear(), start.getMonth(), start.getDate() + 7);
+    return new Date(start.getFullYear(), start.getMonth() + 1, 1);
+}
+const periodStartIso = (period, now) => periodStart(period, now).toISOString();
+exports.periodStartIso = periodStartIso;
+const periodResetsAtIso = (period, now) => periodEnd(period, now).toISOString();
+exports.periodResetsAtIso = periodResetsAtIso;
+function isCapExceeded(budgetUsd, spentUsd) {
+    return budgetUsd != null && budgetUsd > 0 && (0, exports.toCents)(spentUsd) >= (0, exports.toCents)(budgetUsd);
+}
+/** Remaining headroom in cents (negative once over). */
+const capHeadroomCents = (status) => (0, exports.toCents)(status.budgetUsd) - (0, exports.toCents)(status.spentUsd);
+exports.capHeadroomCents = capHeadroomCents;
+/**
+ * The tightest cap: the exhausted one that comes first in the given (scope,
+ * period) order, else the one with the least money left. Callers pass the
+ * statuses project-first so the narrower scope wins ties, like the daily gate.
+ */
+function tightestCap(statuses) {
+    let best = null;
+    for (const status of statuses) {
+        if (!best) {
+            best = status;
+            continue;
+        }
+        if (status.exhausted && !best.exhausted) {
+            best = status;
+            continue;
+        }
+        if (status.exhausted === best.exhausted && (0, exports.capHeadroomCents)(status) < (0, exports.capHeadroomCents)(best))
+            best = status;
+    }
+    return best;
+}
+/** The first exhausted cap in order (project day/week/month, then app-wide). */
+function firstExhaustedCap(statuses) {
+    return statuses.find((status) => status.exhausted) ?? null;
+}
+const PERIOD_ADJECTIVE = { day: 'daily', week: 'weekly', month: 'monthly', run: 'per-run' };
+const PERIOD_RESET_WORD = { day: 'daily', week: 'weekly', month: 'monthly' };
+const PERIOD_SPEND = { day: "Today's", week: "This week's", month: "This month's" };
+/**
+ * The stable 409 body for a cap of any period. A daily cap yields EXACTLY the
+ * historical body (no `period` field); week/month add `period` so clients that
+ * predate caps still read a valid daily-budget rejection.
+ */
+function capRejection(status) {
+    const label = status.scope === 'project' ? 'project' : 'app-wide';
+    const where = status.scope === 'project' ? 'Project settings ▸ Budget' : 'Settings ▸ Budget';
+    const adjective = PERIOD_ADJECTIVE[status.period];
+    return {
+        error: 'daily_budget_exceeded',
+        scope: status.scope,
+        ...(status.period === 'day' ? {} : { period: status.period }),
+        budgetUsd: status.budgetUsd,
+        spentUsd: status.spentUsd,
+        resetsAt: status.resetsAt,
+        detail: `${PERIOD_SPEND[status.period]} spend $${status.spentUsd.toFixed(2)} has reached the ${label} ${adjective} budget of $${status.budgetUsd.toFixed(2)}.`,
+        action: `Raise or clear the ${label} ${adjective} budget (${where}), or wait for the ${PERIOD_RESET_WORD[status.period]} reset.`,
+    };
+}
+/** The per-run soft cap crossed by one run's provider-reported cost. */
+function runCapRejection(capUsd, runCostUsd) {
+    return {
+        error: 'daily_budget_exceeded',
+        scope: 'project',
+        period: 'run',
+        budgetUsd: capUsd,
+        spentUsd: runCostUsd,
+        resetsAt: null,
+        detail: `This run's cost $${runCostUsd.toFixed(2)} has reached the per-run cap of $${capUsd.toFixed(2)}.`,
+        action: 'Continue without the cap, or raise the per-run cap, and the run resumes from the next step.',
+    };
+}
+/** Does a run's cost-so-far cross its soft cap? (`null`/0 cap = no cap.) */
+const isRunCapCrossed = (capUsd, runCostUsd) => capUsd != null && capUsd > 0 && (0, exports.toCents)(runCostUsd) >= (0, exports.toCents)(capUsd);
+exports.isRunCapCrossed = isRunCapCrossed;
+/** The tighter (smaller) of the per-run caps that apply; 0/null mean "none". */
+function effectiveRunCap(...caps) {
+    const set = caps.filter((cap) => cap != null && cap > 0);
+    return set.length ? Math.min(...set) : null;
+}
+exports.TRAILING_DAYS = 14;
+/** `YYYY-MM-DD` in LOCAL time. */
+function localDayKey(date) {
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${date.getFullYear()}-${month}-${day}`;
+}
+/**
+ * Month-end projection from the trailing burn: the average of the last
+ * `trailingDays` COMPLETED days (today is partial and excluded) times the days
+ * left after today, added to the month-to-date spend. Integer cents end to end
+ * (the average rounds once). Null when there is no completed day of history —
+ * nothing honest to extrapolate from.
+ */
+function projectMonthEnd(daily, now, monthToDateCents, trailingDays = exports.TRAILING_DAYS) {
+    const todayKey = localDayKey(now);
+    const earliest = new Date(now.getFullYear(), now.getMonth(), now.getDate() - trailingDays);
+    const earliestKey = localDayKey(earliest);
+    const byDay = new Map();
+    for (const point of daily)
+        byDay.set(point.day, (byDay.get(point.day) ?? 0) + point.cents);
+    let total = 0;
+    let observedDays = 0;
+    // Days with no row were days with no spend, but only after the first recorded
+    // day: before it we simply have no history, so it is not averaged in as $0.
+    const firstRecorded = [...byDay.keys()].filter((key) => key >= earliestKey && key < todayKey).sort()[0];
+    if (!firstRecorded)
+        return null;
+    for (let i = trailingDays; i >= 1; i--) {
+        const day = new Date(now.getFullYear(), now.getMonth(), now.getDate() - i);
+        const key = localDayKey(day);
+        if (key < firstRecorded)
+            continue;
+        observedDays++;
+        total += byDay.get(key) ?? 0;
+    }
+    if (observedDays === 0)
+        return null;
+    const avgDailyCents = Math.round(total / observedDays);
+    const daysInMonth = new Date(now.getFullYear(), now.getMonth() + 1, 0).getDate();
+    const remainingDays = Math.max(0, daysInMonth - now.getDate());
+    return {
+        trailingDays: observedDays,
+        avgDailyCents,
+        monthToDateCents,
+        remainingDays,
+        projectedCents: monthToDateCents + avgDailyCents * remainingDays,
+    };
+}

package/server/dist/modules/execution/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.enforceDailyBudgets = exports.sanitizeRecoveredResult = exports.recoverJobUsage = exports.recordJobInvocations = exports.isDependencySatisfied = exports.normalizePendingQueue = void 0;
+exports.toCents = exports.tightestCap = exports.runCapRejection = exports.projectMonthEnd = exports.periodStartIso = exports.periodStart = exports.periodResetsAtIso = exports.periodEnd = exports.localDayKey = exports.isRunCapCrossed = exports.isCapExceeded = exports.fromCents = exports.firstExhaustedCap = exports.effectiveRunCap = exports.capRejection = exports.capHeadroomCents = exports.TRAILING_DAYS = exports.CAP_PERIODS = exports.minimalAgentEnvNames = exports.matchesEnvPattern = exports.buildAgentEnv = exports.agentEnvAllowlist = exports.AGENT_ENV_WINDOWS_ALLOWLIST = exports.AGENT_ENV_SPECRAILS_ALLOWLIST = exports.AGENT_ENV_BASE_ALLOWLIST = exports.localDayStartIso = exports.isDailyBudgetExceeded = exports.dailyBudgetResetsAt = exports.dailyBudgetRejection = exports.evaluateDailyBudgets = exports.enforceDailyBudgets = exports.sanitizeRecoveredResult = exports.recoverJobUsage = exports.recordJobInvocations = exports.isDependencySatisfied = exports.normalizePendingQueue = void 0;
 var scheduling_1 = require("./domain/scheduling");
 Object.defineProperty(exports, "normalizePendingQueue", { enumerable: true, get: function () { return scheduling_1.normalizePendingQueue; } });
 Object.defineProperty(exports, "isDependencySatisfied", { enumerable: true, get: function () { return scheduling_1.isDependencySatisfied; } });
@@ -12,3 +12,36 @@ var usage_1 = require("./domain/usage");
 Object.defineProperty(exports, "sanitizeRecoveredResult", { enumerable: true, get: function () { return usage_1.sanitizeRecoveredResult; } });
 var enforce_budget_1 = require("./application/enforce-budget");
 Object.defineProperty(exports, "enforceDailyBudgets", { enumerable: true, get: function () { return enforce_budget_1.enforceDailyBudgets; } });
+Object.defineProperty(exports, "evaluateDailyBudgets", { enumerable: true, get: function () { return enforce_budget_1.evaluateDailyBudgets; } });
+var daily_budget_1 = require("./domain/daily-budget");
+Object.defineProperty(exports, "dailyBudgetRejection", { enumerable: true, get: function () { return daily_budget_1.dailyBudgetRejection; } });
+Object.defineProperty(exports, "dailyBudgetResetsAt", { enumerable: true, get: function () { return daily_budget_1.dailyBudgetResetsAt; } });
+Object.defineProperty(exports, "isDailyBudgetExceeded", { enumerable: true, get: function () { return daily_budget_1.isDailyBudgetExceeded; } });
+Object.defineProperty(exports, "localDayStartIso", { enumerable: true, get: function () { return daily_budget_1.localDayStartIso; } });
+var agent_env_1 = require("./domain/agent-env");
+Object.defineProperty(exports, "AGENT_ENV_BASE_ALLOWLIST", { enumerable: true, get: function () { return agent_env_1.AGENT_ENV_BASE_ALLOWLIST; } });
+Object.defineProperty(exports, "AGENT_ENV_SPECRAILS_ALLOWLIST", { enumerable: true, get: function () { return agent_env_1.AGENT_ENV_SPECRAILS_ALLOWLIST; } });
+Object.defineProperty(exports, "AGENT_ENV_WINDOWS_ALLOWLIST", { enumerable: true, get: function () { return agent_env_1.AGENT_ENV_WINDOWS_ALLOWLIST; } });
+Object.defineProperty(exports, "agentEnvAllowlist", { enumerable: true, get: function () { return agent_env_1.agentEnvAllowlist; } });
+Object.defineProperty(exports, "buildAgentEnv", { enumerable: true, get: function () { return agent_env_1.buildAgentEnv; } });
+Object.defineProperty(exports, "matchesEnvPattern", { enumerable: true, get: function () { return agent_env_1.matchesEnvPattern; } });
+Object.defineProperty(exports, "minimalAgentEnvNames", { enumerable: true, get: function () { return agent_env_1.minimalAgentEnvNames; } });
+var spend_caps_1 = require("./domain/spend-caps");
+Object.defineProperty(exports, "CAP_PERIODS", { enumerable: true, get: function () { return spend_caps_1.CAP_PERIODS; } });
+Object.defineProperty(exports, "TRAILING_DAYS", { enumerable: true, get: function () { return spend_caps_1.TRAILING_DAYS; } });
+Object.defineProperty(exports, "capHeadroomCents", { enumerable: true, get: function () { return spend_caps_1.capHeadroomCents; } });
+Object.defineProperty(exports, "capRejection", { enumerable: true, get: function () { return spend_caps_1.capRejection; } });
+Object.defineProperty(exports, "effectiveRunCap", { enumerable: true, get: function () { return spend_caps_1.effectiveRunCap; } });
+Object.defineProperty(exports, "firstExhaustedCap", { enumerable: true, get: function () { return spend_caps_1.firstExhaustedCap; } });
+Object.defineProperty(exports, "fromCents", { enumerable: true, get: function () { return spend_caps_1.fromCents; } });
+Object.defineProperty(exports, "isCapExceeded", { enumerable: true, get: function () { return spend_caps_1.isCapExceeded; } });
+Object.defineProperty(exports, "isRunCapCrossed", { enumerable: true, get: function () { return spend_caps_1.isRunCapCrossed; } });
+Object.defineProperty(exports, "localDayKey", { enumerable: true, get: function () { return spend_caps_1.localDayKey; } });
+Object.defineProperty(exports, "periodEnd", { enumerable: true, get: function () { return spend_caps_1.periodEnd; } });
+Object.defineProperty(exports, "periodResetsAtIso", { enumerable: true, get: function () { return spend_caps_1.periodResetsAtIso; } });
+Object.defineProperty(exports, "periodStart", { enumerable: true, get: function () { return spend_caps_1.periodStart; } });
+Object.defineProperty(exports, "periodStartIso", { enumerable: true, get: function () { return spend_caps_1.periodStartIso; } });
+Object.defineProperty(exports, "projectMonthEnd", { enumerable: true, get: function () { return spend_caps_1.projectMonthEnd; } });
+Object.defineProperty(exports, "runCapRejection", { enumerable: true, get: function () { return spend_caps_1.runCapRejection; } });
+Object.defineProperty(exports, "tightestCap", { enumerable: true, get: function () { return spend_caps_1.tightestCap; } });
+Object.defineProperty(exports, "toCents", { enumerable: true, get: function () { return spend_caps_1.toCents; } });

package/server/dist/modules/execution/runtime/budget-overview.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toProjectionView = toProjectionView;
+exports.projectSpend = projectSpend;
+exports.readSpendOverview = readSpendOverview;
+const budget_storage_1 = require("../adapters/budget-storage");
+const spend_caps_1 = require("../domain/spend-caps");
+function toProjectionView(projection) {
+    if (!projection)
+        return null;
+    return {
+        estimate: true,
+        trailingDays: projection.trailingDays,
+        avgDailyUsd: (0, spend_caps_1.fromCents)(projection.avgDailyCents),
+        monthToDateUsd: (0, spend_caps_1.fromCents)(projection.monthToDateCents),
+        remainingDays: projection.remainingDays,
+        projectedUsd: (0, spend_caps_1.fromCents)(projection.projectedCents),
+    };
+}
+function periodSpend(sources, period, at) {
+    const since = (0, spend_caps_1.periodStart)(period, at).toISOString();
+    const byProvider = new Map();
+    for (const { db, projectId } of sources) {
+        let rows;
+        try {
+            rows = db.prepare(`SELECT COALESCE(provider, 'claude') AS provider,
+          COALESCE(SUM(total_cost_usd), 0) AS usd,
+          COALESCE(SUM(CASE WHEN total_cost_usd_estimated = 1 THEN total_cost_usd END), 0) AS est,
+          COUNT(*) AS n,
+          COALESCE(SUM(num_turns), 0) AS turns
+        FROM ai_invocations WHERE project_id = ? AND started_at >= ? GROUP BY COALESCE(provider, 'claude')`).all(projectId, since);
+        }
+        catch {
+            continue;
+        } // an unreadable project adds nothing (fail-open)
+        for (const row of rows) {
+            const entry = byProvider.get(row.provider) ?? { provider: row.provider, usd: 0, estimatedUsd: 0, invocations: 0, turns: 0 };
+            entry.usd += row.usd;
+            entry.estimatedUsd += row.est;
+            entry.invocations += row.n;
+            entry.turns += row.turns;
+            byProvider.set(row.provider, entry);
+        }
+    }
+    const providers = [...byProvider.values()].sort((a, b) => b.usd - a.usd || a.provider.localeCompare(b.provider));
+    return {
+        startsAt: since,
+        resetsAt: (0, spend_caps_1.periodEnd)(period, at).toISOString(),
+        usd: (0, spend_caps_1.fromCents)(providers.reduce((sum, p) => sum + (0, spend_caps_1.toCents)(p.usd), 0)),
+        estimatedUsd: (0, spend_caps_1.fromCents)(providers.reduce((sum, p) => sum + (0, spend_caps_1.toCents)(p.estimatedUsd), 0)),
+        byProvider: providers,
+    };
+}
+/** Month-end projection for a set of projects: the trailing burn of all of them combined. */
+function projectSpend(sources, at, monthToDateCents) {
+    const since = new Date(at.getFullYear(), at.getMonth(), at.getDate() - spend_caps_1.TRAILING_DAYS).toISOString();
+    const byDay = new Map();
+    for (const { db, projectId } of sources) {
+        try {
+            for (const point of (0, budget_storage_1.projectDailySpend)(db, projectId, since))
+                byDay.set(point.day, (byDay.get(point.day) ?? 0) + point.cents);
+        }
+        catch { /* skipped */ }
+    }
+    return (0, spend_caps_1.projectMonthEnd)([...byDay].map(([day, cents]) => ({ day, cents })), at, monthToDateCents);
+}
+function readSpendOverview(sources, at = new Date()) {
+    const spend = {};
+    for (const period of spend_caps_1.CAP_PERIODS)
+        spend[period] = periodSpend(sources, period, at);
+    return {
+        generatedAt: at.toISOString(),
+        spend,
+        projection: toProjectionView(projectSpend(sources, at, (0, spend_caps_1.toCents)(spend.month.usd))),
+    };
+}

package/server/dist/modules/execution/runtime/daily-budget-gate.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCapStatuses = readCapStatuses;
+exports.createDailyBudgetGate = createDailyBudgetGate;
+exports.createDailyBudgetHeadroom = createDailyBudgetHeadroom;
+const daily_budget_1 = require("../domain/daily-budget");
+const spend_caps_1 = require("../domain/spend-caps");
+const budget_storage_1 = require("../adapters/budget-storage");
+/**
+ * Every configured cap with its spend, project scope first (day, week, month)
+ * then app-wide. THE single read the admission gate, the mid-run pause, the
+ * launch forecast, the Budget panel and the inbox all share, so no surface can
+ * disagree about which cap is reached.
+ */
+function readCapStatuses(options, at) {
+    const storage = (0, budget_storage_1.createQueueBudgetStorage)(options.db);
+    const out = [];
+    const push = (scope, period, snapshot) => {
+        if (!snapshot || snapshot.budget == null || !(snapshot.budget > 0))
+            return;
+        out.push({
+            scope,
+            period,
+            budgetUsd: snapshot.budget,
+            spentUsd: snapshot.totalSpend,
+            exhausted: period === 'day' ? (0, daily_budget_1.isDailyBudgetExceeded)(snapshot) : (0, spend_caps_1.isCapExceeded)(snapshot.budget, snapshot.totalSpend),
+            resetsAt: period === 'day' ? (0, daily_budget_1.dailyBudgetResetsAt)(scope, at) : (0, spend_caps_1.periodResetsAtIso)(period, at),
+        });
+    };
+    push('project', 'day', storage.project(options.projectId, () => (0, daily_budget_1.localDayStartIso)(at)));
+    push('project', 'week', storage.projectPeriod(options.projectId, 'week', () => (0, spend_caps_1.periodStartIso)('week', at)));
+    push('project', 'month', storage.projectPeriod(options.projectId, 'month', () => (0, spend_caps_1.periodStartIso)('month', at)));
+    push('desktop', 'day', options.desktop?.() ?? null);
+    push('desktop', 'week', options.desktopPeriod?.('week', at) ?? null);
+    push('desktop', 'month', options.desktopPeriod?.('month', at) ?? null);
+    return out;
+}
+/**
+ * Admission gate for cost-incurring launches outside the queue (rail loops,
+ * loop runs between AI steps). It reads exactly the budget state the queue
+ * enforces and returns the 409 body when a cap is exhausted.
+ *
+ * Fail-open: a budget that cannot be read never blocks work (mirrors the
+ * queue's best-effort enforcement); the failure is logged.
+ */
+function createDailyBudgetGate(options) {
+    const now = options.now ?? (() => new Date());
+    return () => {
+        try {
+            const breach = (0, spend_caps_1.firstExhaustedCap)(readCapStatuses(options, now()));
+            return breach ? (0, spend_caps_1.capRejection)(breach) : null;
+        }
+        catch (error) {
+            console.warn('[daily-budget] budget state unavailable; admitting the launch:', error instanceof Error ? error.message : error);
+            return null;
+        }
+    };
+}
+/**
+ * Read-only view of the same caps the gate enforces, for surfaces that warn
+ * BEFORE a launch (the launch forecast). Picks the cap with the least money
+ * left, so one caution covers all of them. Null when no cap is configured or
+ * it cannot be read (fail-open, like the gate).
+ */
+function createDailyBudgetHeadroom(options) {
+    const now = options.now ?? (() => new Date());
+    return () => {
+        try {
+            const best = (0, spend_caps_1.tightestCap)(readCapStatuses(options, now()));
+            if (!best)
+                return null;
+            return {
+                scope: best.scope,
+                ...(best.period === 'day' ? {} : { period: best.period }),
+                budgetUsd: best.budgetUsd,
+                spentUsd: best.spentUsd,
+                exhausted: best.exhausted,
+                resetsAt: best.resetsAt,
+            };
+        }
+        catch (error) {
+            console.warn('[daily-budget] budget state unavailable for the forecast:', error instanceof Error ? error.message : error);
+            return null;
+        }
+    };
+}

package/server/dist/modules/execution/runtime/interactive-job-session.js

@@ -122,6 +122,7 @@ function zeroUsage() {
 const FINALIZE_KILL_GRACE_MS = 2000;
 class InteractiveJobSession {
     _jobId;
+    _onProviderEvent;
     _projectId;
     _db;
     _adapter;
@@ -207,6 +208,7 @@ class InteractiveJobSession {
     _zombieTimer = null;
     constructor(deps) {
         this._jobId = deps.jobId;
+        this._onProviderEvent = deps.onProviderEvent ?? null;
         this._projectId = deps.projectId;
         this._db = deps.db;
         this._adapter = deps.adapter;
@@ -475,6 +477,12 @@ class InteractiveJobSession {
             parsed = JSON.parse(line);
         }
         catch { /* plain text */ }
+        if (parsed && this._onProviderEvent) {
+            try {
+                this._onProviderEvent(parsed);
+            }
+            catch { /* observers never affect the session */ }
+        }
         // Keep the live roster current before deciding whether a result completes
         // the step or needs the parent to join its unfinished workers.
         this._trackBackgroundTasks(parsed);

package/server/dist/modules/execution/runtime/launch-forecast.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.forecastFromSamples = forecastFromSamples;
+exports.getLaunchForecast = getLaunchForecast;
+const run_duration_stats_1 = require("./run-duration-stats");
+const cents = (usd) => Math.round(usd * 100) / 100;
+function forecastFromSamples(samples) {
+    const costs = samples
+        .map((sample) => sample.costUsd)
+        .filter((cost) => cost !== null)
+        .sort((a, b) => a - b);
+    return {
+        time: (0, run_duration_stats_1.rangeFromSamples)(samples.map((sample) => sample.ms)),
+        cost: costs.length < run_duration_stats_1.MIN_DURATION_SAMPLES
+            ? null
+            : { lowUsd: cents((0, run_duration_stats_1.percentileMs)(costs, 0.25)), highUsd: cents((0, run_duration_stats_1.percentileMs)(costs, 0.75)), sampleCount: costs.length },
+        minSamples: run_duration_stats_1.MIN_DURATION_SAMPLES,
+    };
+}
+/** The legacy rail modes run as queue jobs under a slash command, not as loop runs. */
+const FACTORY_COMMAND = {
+    'factory:implement': '/specrails:implement',
+    'factory:batch': '/specrails:implement',
+    'factory:freestyle': '/specrails:freestyle',
+};
+function getLaunchForecast(db, projectId, target) {
+    const provider = target.provider || null;
+    const factoryCommand = target.loopId ? FACTORY_COMMAND[target.loopId] : undefined;
+    if (target.loopId && !factoryCommand)
+        return forecastFromSamples((0, run_duration_stats_1.loopRunSamples)(db, projectId, target.loopId, provider));
+    const shape = factoryCommand ?? target.commandShape;
+    return forecastFromSamples(shape ? (0, run_duration_stats_1.jobCommandSamples)(db, shape, provider) : []);
+}