specrails-desktop 2.58.1 → 2.59.1

package/docs/tracking-cost.md

@@ -1,7 +1,5 @@
 # Tracking cost
 
-specrails-desktop records AI CLI invocations across Claude, Codex, Gemini, and Kimi and surfaces the available metrics on one Analytics page per project. This guide walks through what's tracked, what's unavailable, and how to read the dashboard.
-
 ## What gets tracked
 
 Six surfaces, all per-project:
@@ -15,18 +13,6 @@ Six surfaces, all per-project:
 | **`smash`** | SMASH runs that break an epic spec into sub-specs |
 | **`file-summary`** | Code-explorer AI summaries of individual files |
 
-Each invocation row carries the provider, model, status, timestamps, duration,
-and relevant ticket/conversation IDs. Token, USD-cost, and turn fields are
-nullable because not every CLI reports them; Kimi leaves those values
-unavailable rather than writing zero.
-
-The surface list is app-wide, not a promise that every provider can spawn
-every row type. Kimi records its agentic chats/Explore/rails/loops, but Quick
-Spec, AI Edit, Contract Refine, SMASH/Re-SMASH, file summaries, construction
-story, AI auto-title, Project Builder blueprint/milestone generation, Loop
-Decider, and Agent Studio automation fail before spawn. Those rejected
-requests create no invocation row; AI auto-title uses a deterministic fallback.
-
 > Cost averages exclude `failed`/`aborted` rows, but those rows still count toward the total run count and the failure rate.
 
 ## Authoritative vs estimated cost
@@ -34,24 +20,16 @@ requests create no invocation row; AI auto-title uses a deterministic fallback.
 Whether a cost figure is exact depends on the provider's CLI, not on which provider you picked:
 
 - **Claude cost is provider-billed and authoritative** — the figure comes straight from the CLI's own usage report.
-- **Codex and Gemini do not report cost natively**, so the app **estimates** their cost from a local rate-card (`server/modules/accounting/runtime/pricing.ts`) using the captured token counts. Estimated rows are flagged: they render with a `~` tilde in the raw table (hover for the tooltip — *"Estimated from local pricing table — this provider does not report cost natively"*) and feed an "includes ~$X estimated" footnote in the Hero.
-- **Kimi reports neither token counts nor a native USD-cost envelope** in its
-  stream. Specrails does not invent an estimate: cost and token cells stay
-  unavailable.
+- **Codex do not report cost natively**, so the app **estimates** their cost from a local rate-card (`server/modules/accounting/runtime/pricing.ts`) using the captured token counts. Estimated rows are flagged: they render with a `~` tilde in the raw table (hover for the tooltip — *"Estimated from local pricing table — this provider does not report cost natively"*) and feed an "includes ~$X estimated" footnote in the Hero.
 
 On multi-provider projects, a **Provider breakdown** card splits spend across the project's installed engines so you can see authoritative vs estimated at a glance.
 
-> **Fail-soft on unknown models.** The rate card lists specific models (the current Codex and Gemini catalogs). If an invocation uses a model that isn't in the table, the app **does not fabricate a number** — it stores no cost (`total_cost_usd` is left empty), so that row simply shows a blank cost rather than a misleading estimate.
+> **Fail-soft on unknown models.** The rate card lists specific models (the current Codex catalogs). If an invocation uses a model that isn't in the table, the app **does not fabricate a number** — it stores no cost (`total_cost_usd` is left empty), so that row simply shows a blank cost rather than a misleading estimate.
 
 ## What's NOT tracked (intentionally)
 
-- **Sidebar chat** — the general-purpose chat panel in the right sidebar. It spawns an AI process, including `kimi -p` when Kimi is selected, but isn't pipeline work, so the app excludes it from analytics by design.
 - **Setup wizard** — the install/enrich flow when you add a project. It *does* spawn an AI CLI (a genuine model invocation), but it's an interactive one-time wizard rather than a repeatable pipeline job, so it's deliberately left uninstrumented.
 
-If you want the absolute total of what an engine has cost you, your provider's
-own console is the source of truth. This is especially important for Kimi,
-whose CLI stream provides no billable usage envelope to Desktop.
-
 ## The Analytics page
 
 Open **Analytics** from the project right sidebar.
@@ -75,13 +53,6 @@ The big number at the top is total spend in the selected period, with:
 
 When the project has zero invocations in the period (e.g. you just started), the Hero shows "Tracking started YYYY-MM-DD" — the date of the first invocation ever recorded. There's no historical backfill; tracking begins at that first row.
 
-### Provider breakdown
-
-On multi-provider projects, a dedicated card splits available spend across the
-project's installed engines. It is data-driven, so Kimi appears even though its
-cost is unavailable. Estimated Codex/Gemini totals carry a `~` tilde. The card
-is hidden on single-provider projects.
-
 ### Daily stacked timeline
 
 A daily bar chart for the period, stacked by surface. It plots five series — **Jobs, Explore, Quick, Refine, and File summaries**. SMASH spend is still tracked and shows up elsewhere (the Hero per-surface bar, Top models, and the raw table), but it is not currently a separate bar in this chart. Days with zero activity are zero-filled so the x-axis stays regular.
@@ -176,8 +147,6 @@ For the cross-project view, open **Analytics** from the Arc sidebar on the left.
 - [Customising the app](customizing.md) — set the budget, configure notifications.
 - [Creating specs](creating-specs.md) — every spec you create adds rows to your analytics.
 - [Using Codex](codex.md) — how cost works when you run a project on Codex (estimated, ~ tilde).
-- [Using Gemini](gemini.md) — how cost works when you run a project on Gemini (also estimated, ~ tilde).
-- [Using Kimi](kimi.md) — why Kimi duration/outcome are recorded while tokens and cost remain unavailable.
 
 ## Legacy workflow usage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.58.1",
+  "version": "2.59.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/core-execution.js

@@ -51,16 +51,15 @@ function checkoutSubdirectory(directory) {
 function registeredScope(checkout, sourcePath) {
     if (!sourcePath)
         return undefined;
-    const prefix = checkoutSubdirectory(sourcePath);
-    // Core already receives the registered directory itself when it is not a checkout root.
-    if (!prefix || checkoutSubdirectory(checkout) !== '')
+    (0, node_fs_1.realpathSync)(sourcePath);
+    const local = (0, node_path_1.relative)(checkout, sourcePath).split(node_path_1.sep).join('/');
+    const contained = local && local !== '..' && !local.startsWith('../') && !(0, node_path_1.isAbsolute)(local);
+    const prefix = checkoutSubdirectory(checkout) ? (contained ? local : '') : checkoutSubdirectory(sourcePath) || (contained ? local : '');
+    if (!prefix)
         return undefined;
-    try {
-        return (0, node_fs_1.statSync)((0, node_path_1.join)(checkout, ...prefix.split('/'))).isDirectory() ? [prefix] : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    if (!(0, node_fs_1.statSync)((0, node_path_1.join)(checkout, ...prefix.split('/'))).isDirectory())
+        throw new Error('Selected code workspace is unavailable in the execution checkout');
+    return [prefix];
 }
 function withoutScope(context) {
     return { ...context, repositories: context.repositories.map(({ scope: _scope, ...repository }) => repository) };
@@ -74,13 +73,17 @@ function prepareCoreExecution(input) {
         throw new Error('Invalid Core execution run id');
     const cwd = (0, node_fs_1.realpathSync)(input.cwd);
     (0, core_update_state_1.assertWorkspaceCoreReady)(cwd);
-    const scoped = (repository, sourcePath) => {
-        const scope = registeredScope(repository.path, sourcePath);
-        return scope ? { ...repository, scope } : repository;
+    const scoped = (repository, sourcePath, workspacePaths, selectedWorkspacePaths) => {
+        const scope = workspacePaths?.length ? [...new Set(workspacePaths.flatMap(workspace => registeredScope(repository.path, workspace) ?? []))] : registeredScope(repository.path, sourcePath);
+        if (selectedWorkspacePaths) {
+            const selectedScope = [...new Set(selectedWorkspacePaths.flatMap(workspace => registeredScope(repository.path, workspace) ?? []))];
+            return { ...repository, ...(selectedScope.length ? { scope: selectedScope } : {}), ...(scope?.length ? { registeredScope: scope } : {}) };
+        }
+        return scope?.length ? { ...repository, scope } : repository;
     };
     const repositories = manifest
-        ? manifest.repositories.map(repo => scoped({ id: repo.repositoryId, name: repo.name, path: (0, node_fs_1.realpathSync)(repo.worktreePath), baseSha: repo.baseSha }, repo.sourcePath))
-        : [scoped({ id: run.repositoryId ?? (run.spec?.repositoryIds?.length === 1 ? run.spec.repositoryIds[0] : run.projectId ? `primary-${run.projectId}` : 'primary'), name: (0, node_path_1.basename)(input.repoDir ?? cwd), path: (0, node_fs_1.realpathSync)(input.repoDir ?? cwd) }, input.sourcePath)];
+        ? manifest.repositories.map(repo => scoped({ id: repo.repositoryId, name: repo.name, path: (0, node_fs_1.realpathSync)(repo.worktreePath), baseSha: repo.baseSha }, repo.workspacePath ?? repo.sourcePath, repo.workspacePaths, repo.selectedWorkspacePaths))
+        : [scoped({ id: run.repositoryId ?? (run.spec?.repositoryIds?.length === 1 ? run.spec.repositoryIds[0] : run.projectId ? `primary-${run.projectId}` : 'primary'), name: (0, node_path_1.basename)(input.repoDir ?? cwd), path: (0, node_fs_1.realpathSync)(input.repoDir ?? cwd) }, input.sourcePath, input.workspacePaths, input.selectedWorkspacePaths)];
     if (!repositories.length || repositories.some(repo => !SAFE_ID.test(repo.id)))
         throw new Error('Invalid Core repository scope');
     const artifactRepositoryId = manifest?.artifactRepositoryId ?? repositories[0].id;
@@ -127,7 +130,13 @@ function prepareCoreExecution(input) {
     }
     const env = { ...input.env, SPECRAILS_EXECUTION_CONTEXT: contextPath };
     const promptPrefix = run.verificationStep ? coreVerificationContext(contextPath, cwd, env, run.runId) : '';
-    return { env, contextPath, promptPrefix };
+    const frozen = JSON.parse((0, node_fs_1.readFileSync)(contextPath, 'utf8'));
+    const workspaceBriefing = [
+        'Code workspaces frozen for this run (the project folder and the internal agent workspace are not test targets):',
+        ...frozen.repositories.map(repo => JSON.stringify({ repositoryId: repo.id, name: repo.name, checkout: repo.path, workspaces: (repo.scope ?? ['.']).map(scope => (0, node_path_1.resolve)(repo.path, scope)) })),
+        'Run tests, builds and other checks in these code workspace directories. For a manual shell command, set its cwd explicitly or cd to the exact workspace first. Do not use the parent project directory or another workspace as a fallback. For multiple workspaces, verify each selected workspace separately. If a workspace or its test command is unavailable, report the blocker.',
+    ].join('\n');
+    return { env, contextPath, promptPrefix: [workspaceBriefing, promptPrefix].filter(Boolean).join('\n\n'), workspaceBriefing };
 }
 /** Ask the installed Core runtime to validate its own receipts. Desktop never
  * treats an agent-authored summary or a JSON 'pass' field as verification.

package/server/dist/core-update-manager.js

@@ -73,7 +73,7 @@ class CoreUpdateManager {
             this.latestVersion != null &&
                 currentVersion != null &&
                 ((0, semver_lite_1.isNewer)(this.latestVersion, currentVersion) || selected.error !== null && this.latestVersion === currentVersion) &&
-                Number(this.latestVersion.split('.')[0]) <= 5;
+                (0, core_package_1.isSupportedCoreVersion)(this.latestVersion);
         return {
             available: this.isAvailable(),
             currentVersion,

package/server/dist/db/migrations.js

@@ -1608,6 +1608,15 @@ const MIGRATIONS = [
     (db) => {
         db.exec(`UPDATE rails SET mode='implement' WHERE mode IN ('batch-implement','batch')`);
     },
+    // Migration 71: source-bound rail relaunch. NULL preserves historical rows;
+    // new attempts freeze their admitted launch options before agent execution.
+    (db) => {
+        for (const table of ['rail_pr_deliveries', 'loop_runs']) {
+            const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+            if (!columns.some(column => column.name === 'launch_config_json'))
+                db.exec(`ALTER TABLE ${table} ADD COLUMN launch_config_json TEXT`);
+        }
+    },
 ];
 function applyMigrations(db) {
     // Ensure the migrations table exists (migration 1 creates it, but we need

package/server/dist/desktop-db.js

@@ -675,6 +675,14 @@ function applyDesktopMigrations(db) {
         UPDATE loops SET published_graph = graph WHERE status = 'published' AND published_graph IS NULL;
       `);
         },
+        // 32: explicit code workspace; old memberships continue to use their root.
+        () => {
+            const columns = db.prepare('PRAGMA table_info(project_repositories)').all().map(column => column.name);
+            if (!columns.includes('workspace_path'))
+                db.exec('ALTER TABLE project_repositories ADD COLUMN workspace_path TEXT');
+            if (!columns.includes('workspace_paths'))
+                db.exec('ALTER TABLE project_repositories ADD COLUMN workspace_paths TEXT');
+        },
     ];
     (0, sqlite_migrations_1.applyNumberedMigrations)(db, migrations);
 }
@@ -726,15 +734,15 @@ function addProject(db, project) {
     const provider = project.provider ?? providers[0];
     // Low-level callers may register unavailable legacy roots. HTTP validates all
     // roots first; membership and project rows are still committed atomically here.
-    const roots = [(0, project_repositories_1.inspectRepositoryPath)({ path: project.path, name: project.name }, false), ...(project.repositories ?? []).map((input) => (0, project_repositories_1.inspectRepositoryPath)(input))];
+    const roots = [(0, project_repositories_1.inspectRepositoryPath)({ path: project.path, name: project.name, workspacePaths: project.workspacePaths }, project.workspacePaths !== undefined), ...(project.repositories ?? []).map((input) => (0, project_repositories_1.inspectRepositoryPath)(input))];
     (0, project_repositories_1.assertDistinctRepositories)(roots);
     db.transaction(() => {
         db.prepare(`
       INSERT INTO projects (id, slug, name, path, db_path, provider, providers)
       VALUES (?, ?, ?, ?, ?, ?, ?)
     `).run(project.id, project.slug, project.name, project.path, dbPath, provider, JSON.stringify(providers));
-        const insert = db.prepare(`INSERT INTO project_repositories (id, project_id, name, path, canonical_key, git_identity, is_primary, kind, integration_branch) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-        roots.forEach((root, index) => insert.run(index === 0 ? `primary-${project.id}` : (0, crypto_1.randomUUID)(), project.id, root.name ?? path_1.default.basename(root.path), index === 0 ? project.path : root.path, root.canonicalKey, root.gitIdentity, index === 0 ? 1 : 0, root.kind, root.integrationBranch ?? null));
+        const insert = db.prepare(`INSERT INTO project_repositories (id, project_id, name, path, canonical_key, git_identity, is_primary, kind, integration_branch, workspace_path, workspace_paths) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        roots.forEach((root, index) => insert.run(index === 0 ? `primary-${project.id}` : (0, crypto_1.randomUUID)(), project.id, root.name ?? path_1.default.basename(root.path), index === 0 ? project.path : root.path, root.canonicalKey, root.gitIdentity, index === 0 ? 1 : 0, root.kind, root.integrationBranch ?? null, root.workspacePath ?? null, root.workspacePaths ? JSON.stringify(root.workspacePaths) : null));
     })();
     return getProject(db, project.id);
 }
@@ -742,7 +750,9 @@ function listProjectRepositories(db, projectId) {
     return db.prepare('SELECT * FROM project_repositories WHERE project_id = ? ORDER BY is_primary DESC, added_at, rowid').all(projectId).map((row) => ({
         id: row.id, projectId: row.project_id, name: row.name, path: row.path,
         isPrimary: row.is_primary === 1, kind: row.kind, integrationBranch: row.integration_branch,
-        addedAt: row.added_at, available: (0, project_repositories_1.repositoryAvailable)(row.path),
+        addedAt: row.added_at, available: (0, project_repositories_1.repositoryAvailable)(row.path) && (row.workspace_paths ? JSON.parse(row.workspace_paths).every(project_repositories_1.repositoryAvailable) : (0, project_repositories_1.repositoryAvailable)(row.workspace_path ?? row.path)),
+        ...(row.workspace_path ? { workspacePath: row.workspace_path } : {}),
+        ...(row.workspace_paths ? { workspacePaths: JSON.parse(row.workspace_paths) } : {}),
     }));
 }
 function addProjectRepository(db, projectId, input) {
@@ -752,8 +762,8 @@ function addProjectRepository(db, projectId, input) {
     const existing = listProjectRepositories(db, projectId).map((repo) => (0, project_repositories_1.inspectRepositoryPath)(repo, false));
     (0, project_repositories_1.assertDistinctRepositories)([...existing, root]);
     const id = (0, crypto_1.randomUUID)();
-    db.prepare(`INSERT INTO project_repositories (id, project_id, name, path, canonical_key, git_identity, kind, integration_branch) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
-        .run(id, projectId, root.name ?? path_1.default.basename(root.path), root.path, root.canonicalKey, root.gitIdentity, root.kind, root.integrationBranch ?? null);
+    db.prepare(`INSERT INTO project_repositories (id, project_id, name, path, canonical_key, git_identity, kind, integration_branch, workspace_path, workspace_paths) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(id, projectId, root.name ?? path_1.default.basename(root.path), root.path, root.canonicalKey, root.gitIdentity, root.kind, root.integrationBranch ?? null, root.workspacePath ?? null, root.workspacePaths ? JSON.stringify(root.workspacePaths) : null);
     return listProjectRepositories(db, projectId).find((repo) => repo.id === id);
 }
 function updateProjectRepository(db, projectId, repositoryId, input) {
@@ -763,15 +773,18 @@ function updateProjectRepository(db, projectId, repositoryId, input) {
         throw new project_repositories_1.RepositoryValidationError('Repository does not belong to this project', 'repository_not_found', 404);
     if (current.isPrimary && input.path !== undefined)
         throw new project_repositories_1.RepositoryValidationError('The primary project path cannot be relocated here', 'primary_repository_protected', 409);
-    const next = { ...current, ...input };
-    const root = (0, project_repositories_1.inspectRepositoryPath)(next, input.path !== undefined);
+    const next = { ...current, ...input,
+        ...(input.workspacePaths !== undefined && input.workspacePath === undefined ? { workspacePath: null } : {}),
+        ...(input.workspacePath !== undefined && input.workspacePaths === undefined ? { workspacePaths: null } : {}),
+    };
+    const root = (0, project_repositories_1.inspectRepositoryPath)(next, input.path !== undefined || input.workspacePath !== undefined || input.workspacePaths !== undefined);
     if (input.path === undefined && !(0, project_repositories_1.repositoryAvailable)(current.path)) {
         root.kind = current.kind;
         root.gitIdentity = db.prepare('SELECT git_identity FROM project_repositories WHERE id = ?').get(repositoryId).git_identity;
     }
     (0, project_repositories_1.assertDistinctRepositories)([...repositories.filter((repo) => repo.id !== repositoryId).map((repo) => (0, project_repositories_1.inspectRepositoryPath)(repo, false)), root]);
-    db.prepare('UPDATE project_repositories SET name = ?, path = ?, canonical_key = ?, git_identity = ?, kind = ?, integration_branch = ? WHERE project_id = ? AND id = ?')
-        .run(root.name ?? current.name, input.path === undefined ? current.path : root.path, root.canonicalKey, root.gitIdentity, root.kind, root.integrationBranch ?? null, projectId, repositoryId);
+    db.prepare('UPDATE project_repositories SET name = ?, path = ?, canonical_key = ?, git_identity = ?, kind = ?, integration_branch = ?, workspace_path = ?, workspace_paths = ? WHERE project_id = ? AND id = ?')
+        .run(root.name ?? current.name, input.path === undefined ? current.path : root.path, root.canonicalKey, root.gitIdentity, root.kind, root.integrationBranch ?? null, root.workspacePath ?? null, root.workspacePaths ? JSON.stringify(root.workspacePaths) : null, projectId, repositoryId);
     return listProjectRepositories(db, projectId).find((repo) => repo.id === repositoryId);
 }
 /** Removes the association only. Operational reference guards belong to ProjectRegistry. */

package/server/dist/desktop-router.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDesktopRouter = createDesktopRouter;
+const http_1 = require("./modules/subscription-usage/adapters/http");
 const runtime_role_prompts_router_1 = require("./runtime-role-prompts-router");
 const express_1 = require("express");
 const agent_runtime_settings_1 = require("./modules/agent-runtime/runtime/agent-runtime-settings");
@@ -319,8 +320,10 @@ function publicWebhook(row) {
     const { secret: _secret, ...rest } = row;
     return { ...rest, hasSecret: row.secret.length > 0 };
 }
-function createDesktopRouter(registry, broadcast) {
+function createDesktopRouter(registry, broadcast, usageService) {
     const router = (0, express_1.Router)();
+    if (usageService)
+        (0, http_1.registerUsageRoutes)(router, usageService);
     // Loops (global, cross-project library) — /api/loops*. Registered here so the
     // routes live on the global `/api` router (loops are NOT project-scoped). The
     // A loop is "running" iff any project's per-project DB has an in-flight
@@ -476,7 +479,7 @@ function createDesktopRouter(registry, broadcast) {
     });
     // POST /api/projects — register a new project by path
     router.post('/projects', async (req, res) => {
-        const { path: projectPath, name, provider, providers: providersRaw, repositories: repositoriesRaw } = req.body ?? {};
+        const { path: projectPath, name, provider, providers: providersRaw, repositories: repositoriesRaw, workspacePaths } = req.body ?? {};
         if (!projectPath || typeof projectPath !== 'string') {
             res.status(400).json({ error: 'path is required' });
             return;
@@ -573,7 +576,7 @@ function createDesktopRouter(registry, broadcast) {
             if (repositoriesRaw !== undefined && !Array.isArray(repositoriesRaw))
                 throw new project_repositories_1.RepositoryValidationError('repositories must be an array');
             repositories = (repositoriesRaw ?? []).map((input) => (0, project_repositories_1.inspectRepositoryPath)(input));
-            const primary = (0, project_repositories_1.inspectRepositoryPath)({ path: canonicalPath });
+            const primary = (0, project_repositories_1.inspectRepositoryPath)({ path: canonicalPath, workspacePaths });
             (0, project_repositories_1.assertDistinctRepositories)([primary, ...repositories.map((input) => (0, project_repositories_1.inspectRepositoryPath)(input))]);
             if (repositories.some((repository) => !isPathSafe(repository.path)))
                 throw new project_repositories_1.RepositoryValidationError('Registering system directories is not allowed');
@@ -609,6 +612,7 @@ function createDesktopRouter(registry, broadcast) {
                 provider: providers[0],
                 providers,
                 repositories,
+                workspacePaths,
             });
             broadcast({
                 type: 'desktop.project_added',
@@ -681,7 +685,7 @@ function createDesktopRouter(registry, broadcast) {
         try {
             const body = req.body ?? {};
             const input = {};
-            for (const key of ['path', 'name', 'integrationBranch'])
+            for (const key of ['path', 'name', 'integrationBranch', 'workspacePath', 'workspacePaths'])
                 if (Object.prototype.hasOwnProperty.call(body, key))
                     Object.assign(input, { [key]: body[key] });
             if (input.path !== undefined) {

package/server/dist/index.js

@@ -1,12 +1,13 @@
 "use strict";
-// Note: the pkg-binary native-addon hijacks (better_sqlite3.node, node-pty, pty.node)
-// used to live here but had to move to an esbuild `banner.js` in scripts/build-sidecar.mjs
-// so they run BEFORE esbuild's top-of-bundle `require('node-pty')` statement.
-// See the banner in that script for the actual patches.
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+const composition_1 = require("./modules/subscription-usage/runtime/composition");
+// Note: the pkg-binary native-addon hijacks (better_sqlite3.node, node-pty, pty.node)
+// used to live here but had to move to an esbuild `banner.js` in scripts/build-sidecar.mjs
+// so they run BEFORE esbuild's top-of-bundle `require('node-pty')` statement.
+// See the banner in that script for the actual patches.
 const http_1 = __importDefault(require("http"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
@@ -275,6 +276,7 @@ function broadcast(msg) {
 let _getProjectCount = () => 0;
 /** Captured by the Super-mode bootstrap block so graceful shutdown can tear down every
  *  project's spawners (rail/chat children) instead of orphaning them. */
+let _usageService = null;
 let _registry = null;
 /** The mobile companion gateway (off by default); torn down on shutdown. */
 let _mobileGateway = null;
@@ -672,7 +674,9 @@ function applyPtyWsRateLimiting(ws) {
     // GET /api/projects, DELETE /api/projects/:id) are handled here, while
     // everything else under /api/projects/:projectId/* falls through to the
     // project router.
-    app.use('/api', (0, desktop_router_1.createDesktopRouter)(registry, broadcast));
+    const usageService = (0, composition_1.createDesktopUsageService)();
+    _usageService = usageService;
+    app.use('/api', (0, desktop_router_1.createDesktopRouter)(registry, broadcast, usageService));
     // Per-project routes under /api/projects/:projectId/*
     app.use('/api/projects', (0, project_router_1.createProjectRouter)(registry));
     // Return 410 Gone for the old per-project hook endpoint in Super mode
@@ -780,6 +784,7 @@ async function shutdown() {
     // skip Agent Chat, and Headroom must remain available until all routed AI
     // children have received their termination signal.
     await Promise.allSettled([
+        Promise.resolve().then(() => _usageService?.dispose()),
         Promise.resolve().then(() => _registry?.shutdown()),
         Promise.resolve().then(() => (0, terminal_manager_1.getTerminalManager)().shutdown()),
         Promise.resolve().then(() => _mobileGateway?.stop()),

package/server/dist/mcp/guide.js

@@ -28,6 +28,7 @@ Codex, Gemini, Kimi Code) to implement specs.
   \`specrails_projects(get)\` includes the repo's absolute path and availability.
   A registered project with an unavailable database still exists; never create
   a duplicate or interpret unavailable data as an empty backlog.
+- **Code workspace**: a configured code directory inside a repository. A project can have one or many. Discover \`workspacePaths\` with \`specrails_projects(get/repositories)\`; configure them with \`repository_add/repository_update\` (write permission), or register them through \`specrails_setup(add_project)\`. Independent Git roots are separate repository memberships. Launch rails or standalone loops with \`workspaceSelection\` mapping repository IDs to registered paths; omission selects all configured workspaces. Tests run within the selected directories, never implicitly in the project parent.
 - **Repository**: a stable membership within a project, addressed by \`repositoryId\`.
   Discover the inventory in \`specrails_projects(get)\` or \`specrails_context(overview)\`.
   A member is a Git repository or a non-Git context folder. File paths are relative

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

@@ -138,7 +138,7 @@ 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'),
+                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'),
                 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.'),

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

@@ -106,6 +106,7 @@ function loopsTools() {
                     .describe('Project id (run / run_get only — defaults to the active project; ignored by every other action)'),
                 loopId: zod_1.z.string().optional().describe('Loop id (for get / update / publish / unpublish / duplicate / restore_builtin / delete / run — must be Published for run). Built-ins use their factory id, e.g. factory:implement'),
                 repositoryIds: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).optional().describe('run only: repository memberships to include in one coordinated standalone execution; omission retains primary-only behavior.'),
+                workspaceSelection: zod_1.z.record(zod_1.z.string(), zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50)).optional().describe('run only: selected registered code workspace paths per selected repository ID. Omission uses all configured workspaces.'),
                 loopRunId: zod_1.z.string().optional().describe('Loop run id (for run_get — returned by run)'),
                 constantId: zod_1.z.string().optional().describe('Constant id (for constant_update / constant_delete)'),
                 templateId: zod_1.z.string().optional().describe('Template id (for from_template)'),
@@ -270,6 +271,7 @@ function loopsTools() {
                         const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/loop-runs`, {
                             loopId,
                             ...(args.repositoryIds === undefined ? {} : { repositoryIds: args.repositoryIds }),
+                            ...(args.workspaceSelection === undefined ? {} : { workspaceSelection: args.workspaceSelection }),
                             ...(provider !== undefined ? { provider } : {}),
                             ...(model !== undefined ? { model } : {}),
                             ...(effort !== undefined ? { reasoning_effort: effort } : {}),

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

@@ -1,11 +1,8 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.metaTools = metaTools;
 const zod_1 = require("zod");
-const node_path_1 = __importDefault(require("node:path"));
+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");
@@ -162,9 +159,11 @@ function metaTools(getSpecs) {
             handler: (ctx, args) => {
                 if (args.path !== undefined && args.projectId !== undefined)
                     throw new Error('Provide either path or projectId, not both.');
-                const project = args.path
-                    ? ctx.registry.listProjects().find(p => node_path_1.default.resolve(p.path) === node_path_1.default.resolve(String(args.path)))
-                    : typeof args.projectId === 'string' ? ctx.registry.getProjectRow(args.projectId) : undefined;
+                const key = args.path ? (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(String(args.path))) : undefined;
+                const matches = key ? ctx.registry.listProjects().filter(project => (0, project_repositories_1.getProjectRepositories)(project).some(repository => [repository.path, ...(repository.workspacePaths ?? (repository.workspacePath ? [repository.workspacePath] : []))].some(root => (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(root)) === key))) : [];
+                if (matches.length > 1)
+                    throw new Error('Ambiguous project path; provide an explicit projectId.');
+                const project = key ? matches[0] : typeof args.projectId === 'string' ? ctx.registry.getProjectRow(args.projectId) : undefined;
                 if (args.path && !project)
                     throw new Error(`No project registered at path "${args.path}".`);
                 if (args.projectId && !project)

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

@@ -25,17 +25,42 @@ function projectsTools() {
             name: 'specrails_projects',
             title: 'Projects',
             description: 'List and inspect registered Specrails projects, resolve a project by filesystem path, or unregister one. ' +
-                'Actions: list, get, resolve (by path), unregister (destructive — removes the project and its workspace).',
+                'Actions: list, get, resolve (by project/repository/workspace path), repositories (inventory), repository_add / repository_update (write, configure registered code workspacePaths), repository_remove (destructive), unregister (destructive — removes the project and its workspace).',
             hintTier: 'read',
-            tier: (args) => (args.action === 'unregister' ? 'destructive' : 'read'),
+            tier: (args) => ['unregister', 'repository_remove'].includes(String(args.action)) ? 'destructive' : ['repository_add', 'repository_update'].includes(String(args.action)) ? 'write' : 'read',
             inputSchema: {
-                action: zod_1.z.enum(['list', 'get', 'resolve', 'unregister']).describe('Operation to perform'),
-                projectId: zod_1.z.string().optional().describe('Project id (for get / unregister)'),
-                path: zod_1.z.string().optional().describe('Filesystem path (for resolve)'),
+                action: zod_1.z.enum(['list', 'get', 'resolve', 'repositories', 'repository_add', 'repository_update', 'repository_remove', 'unregister']).describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id; defaults to the active project for get and repository operations; required for unregister'),
+                path: zod_1.z.string().optional().describe('Filesystem path for resolve or repository_add/update; repository root retains its Git/delivery identity'),
+                repositoryId: zod_1.z.string().min(1).optional().describe('Required for repository_update/remove; discover from repositories/get'),
+                name: zod_1.z.string().min(1).optional().describe('Repository display name'),
+                integrationBranch: zod_1.z.string().nullable().optional().describe('Repository integration branch; null clears it'),
+                workspacePaths: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).nullable().optional().describe('repository_add/update: code directories inside the repository, absolute or root-relative. null resets to repository root. Independent Git roots need separate memberships. Changes are rejected while active runs depend on this scope.'),
             },
             handler: (ctx, args) => {
                 const action = args.action;
                 switch (action) {
+                    case 'repositories':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${(0, types_1.projectPath)(ctx, args.projectId)}/repositories`);
+                    case 'repository_add':
+                    case 'repository_update':
+                    case 'repository_remove': {
+                        const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/repositories`;
+                        const id = args.repositoryId;
+                        if (action !== 'repository_add' && !id)
+                            throw new Error(`${action} requires repositoryId.`);
+                        if (action === 'repository_remove')
+                            return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/${encodeURIComponent(id)}`);
+                        if (action === 'repository_add' && !args.path)
+                            throw new Error('repository_add requires path.');
+                        const body = {};
+                        for (const key of ['path', 'name', 'integrationBranch', 'workspacePaths'])
+                            if (args[key] !== undefined)
+                                body[key] = args[key];
+                        if (!Object.keys(body).length)
+                            throw new Error('repository_update requires at least one field to update.');
+                        return (0, types_1.apiCall)(ctx, action === 'repository_add' ? 'POST' : 'PATCH', action === 'repository_add' ? base : `${base}/${encodeURIComponent(id)}`, body);
+                    }
                     case 'list':
                         return ctx.registry.listProjects().map((p) => ({ ...serializeProject(p), available: !!ctx.registry.getContext(p.id) }));
                     case 'get': {
@@ -53,7 +78,7 @@ function projectsTools() {
                             throw new Error('resolve requires a "path".');
                         const selected = args.projectId;
                         const key = (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(p));
-                        const matches = ctx.registry.listProjects().filter(row => !selected || row.id === selected).flatMap(project => (0, project_repositories_1.getProjectRepositories)(project).filter(repository => (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(repository.path)) === key)
+                        const matches = ctx.registry.listProjects().filter(row => !selected || row.id === selected).flatMap(project => (0, project_repositories_1.getProjectRepositories)(project).filter(repository => [repository.path, ...(repository.workspacePaths ?? (repository.workspacePath ? [repository.workspacePath] : []))].some(root => (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(root)) === key))
                             .map(repository => ({ project, repository })));
                         if (matches.length > 1)
                             return { resolved: false, ambiguous: true, matches: matches.map(({ project, repository }) => ({ projectId: project.id, projectName: project.name, repositoryId: repository.id, repositoryName: repository.name })) };

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

@@ -49,7 +49,7 @@ function railsTools() {
                 'When launched from the in-app agent chat without an explicit aiEngine, the engine defaults to your conversation\'s provider. On that same provider, an omitted model inherits the conversation model; an explicit model wins (pass aiEngine to override; launch_all always uses each rail\'s stored engine). ' +
                 'For Implement, the selected launch provider applies to ALL runtime roles (architect, developer, reviewer); an explicit launch model/effort also applies to each role. Resuming an existing execution keeps its original frozen role configuration; start a new launch to change providers. ' +
                 'User-facing naming: call the free-form autonomous mode "Freestyle"; use "freestyle" as the canonical API enum value for that same capability. ' +
-                'For small OpenSpec-governed work, recommend "SDD Quick (OpenSpec)" and launch with mode "loop" plus loopId "factory:sdd-quick-openspec"; keep Freestyle for ticket-local implementation-only work. ' +
+                'Always honor an explicit workflow selection, including Implement for addenda or delivery changes. Without a preference, for small OpenSpec-governed work, recommend "SDD Quick (OpenSpec)" and launch with mode "loop" plus loopId "factory:sdd-quick-openspec"; keep Freestyle for ticket-local implementation-only work. ' +
                 'NAMING: railIndex is the 0-BASED internal identity; the dashboard shows rails 1-based ("Rail N" = railIndex N-1). When talking to the user, ALWAYS say "Rail <railIndex + 1>" (or the rail\'s custom name) — results include railLabel with the correct user-facing label.',
             hintTier: 'read',
             tier: (a) => {
@@ -68,6 +68,7 @@ function railsTools() {
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
                 repositoryIds: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).optional().describe('launch only: explicit affected repository memberships for the coordinated run; must include every repository required by the assigned specs. Omission uses the assigned specs\' repository selections.'),
+                workspaceSelection: zod_1.z.record(zod_1.z.string(), zod_1.z.array(zod_1.z.string().min(1)).min(1)).optional().describe('launch only: map selected repository IDs to registered code workspace paths; discover workspacePaths through project context. Omission verifies all configured code workspaces. Never use the parent project path unless it is itself a registered code workspace.'),
                 repositoryId: zod_1.z.string().min(1).optional().describe('review_packet only: member of a grouped delivery to inspect; omission returns the public parent with grouped outcomes.'),
                 railIndex: zod_1.z
                     .number()
@@ -129,11 +130,11 @@ function railsTools() {
                 revisionOfDeliveryId: zod_1.z
                     .string()
                     .optional()
-                    .describe('Revise a delivery that is ALREADY awaiting the user\'s decision (launch). Continues with Quick SDD (the Revision loop is retired): pass its prDeliveryId (from rails.prDeliveries) together with revisionNote. Use it whenever the user asks for a change to work you already delivered — never publish/discard/merge first. The rail must still carry exactly that delivery\'s specs.'),
+                    .describe('Revise a delivery that is ALREADY awaiting the user\'s decision (launch). Continues with the explicitly selected loop, defaulting to Quick SDD (the Revision loop is retired): pass its prDeliveryId (from rails.prDeliveries) together with revisionNote. Use it whenever the user asks for a change to work you already delivered — never publish/discard/merge first. The rail must still carry exactly that delivery\'s specs.'),
                 revisionNote: zod_1.z
                     .string()
                     .optional()
-                    .describe('What to change, in the user\'s own words (required with revisionOfDeliveryId). It is injected into every Quick SDD phase and shown on the updated review packet as "what you asked to change".'),
+                    .describe('What to change, in the user\'s own words (required with revisionOfDeliveryId). It is injected into every selected workflow phase and shown on the updated review packet as "what you asked to change".'),
                 followUp: zod_1.z
                     .object({
                     comments: zod_1.z.array(zod_1.z.object({
@@ -257,6 +258,8 @@ function railsTools() {
                             body.targetPrNumber = args.targetPrNumber;
                         if (args.repositoryIds !== undefined)
                             body.repositoryIds = args.repositoryIds;
+                        if (args.workspaceSelection !== undefined)
+                            body.workspaceSelection = args.workspaceSelection;
                         if (args.baseBranch !== undefined)
                             body.baseBranch = args.baseBranch;
                         // Revision of a delivery already awaiting the user's decision: the

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

@@ -88,6 +88,8 @@ function setupTools() {
                     .array(zod_1.z.string())
                     .optional()
                     .describe('add_project: providers to install (first = primary/default); de-duped server-side'),
+                workspacePaths: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).optional().describe('add_project: code workspace directories inside the primary project root'),
+                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())
@@ -115,6 +117,10 @@ function setupTools() {
                             body.provider = args.provider;
                         if (Array.isArray(args.providers))
                             body.providers = args.providers;
+                        if (args.workspacePaths !== undefined)
+                            body.workspacePaths = args.workspacePaths;
+                        if (args.repositories !== undefined)
+                            body.repositories = args.repositories;
                         return (0, types_1.apiCall)(ctx, 'POST', '/projects', body);
                     }
                     // ─── Per-project ────────────────────────────────────────────────────
@@ -137,6 +143,10 @@ function setupTools() {
                         const body = {};
                         if (Array.isArray(args.providers))
                             body.providers = args.providers;
+                        if (args.workspacePaths !== undefined)
+                            body.workspacePaths = args.workspacePaths;
+                        if (args.repositories !== undefined)
+                            body.repositories = args.repositories;
                         else if (typeof args.provider === 'string')
                             body.provider = args.provider;
                         else

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

@@ -313,7 +313,7 @@ function specsTools() {
                         });
                         return {
                             ...r,
-                            hint: 'The addendum is open: launch with factory:sdd-quick-openspec. Rail launches route open addenda to Quick SDD, continue a same-spec pending delivery, and brief every AI step with the full delta and a fresh OpenSpec target. Do not use Revision or edit openspecChangeName. Do not edit the spec description to repeat it.',
+                            hint: 'The addendum is open: respect the user\'s explicit loop selection, including factory:implement; otherwise recommend factory:sdd-quick-openspec. Rail launches continue a same-spec pending delivery, and brief every AI step with the full delta and a fresh OpenSpec target. Do not use Revision or edit openspecChangeName. Do not edit the spec description to repeat it.',
                         };
                     }
                     case 'update_addendum': {

package/server/dist/modules/accounting/runtime/pricing.js

@@ -76,7 +76,10 @@ exports.PRICING = {
     // Opus 5.5: https://platform.claude.com/docs/en/models/opus-5-5/overview
     'claude:opus': { inputPer1M: 4.00, outputPer1M: 20.00, cacheReadPer1M: 0.20, cacheWritePer1M: 5.00, inputIncludesCacheReads: false, lastReviewedAt: '2026-09-24' },
     'claude:claude-opus-5-5': { inputPer1M: 4.00, outputPer1M: 20.00, cacheReadPer1M: 0.20, cacheWritePer1M: 5.00, inputIncludesCacheReads: false, lastReviewedAt: '2026-09-24' },
-    'claude:sonnet': { inputPer1M: 3.00, outputPer1M: 15.00, cacheReadPer1M: 0.30, cacheWritePer1M: 3.75, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
+    'claude:claude-sonnet-5': { inputPer1M: 3.00, outputPer1M: 15.00, cacheReadPer1M: 0.30, cacheWritePer1M: 3.75, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
+    // Sonnet 5.5: https://platform.claude.com/docs/en/models/sonnet-5-5/overview
+    'claude:sonnet': { inputPer1M: 2.00, outputPer1M: 10.00, cacheReadPer1M: 0.20, cacheWritePer1M: 2.50, inputIncludesCacheReads: false, lastReviewedAt: '2026-09-30' },
+    'claude:claude-sonnet-5-5': { inputPer1M: 2.00, outputPer1M: 10.00, cacheReadPer1M: 0.20, cacheWritePer1M: 2.50, inputIncludesCacheReads: false, lastReviewedAt: '2026-09-30' },
     'claude:haiku': { inputPer1M: 1.00, outputPer1M: 5.00, cacheReadPer1M: 0.10, cacheWritePer1M: 1.25, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
     'claude:fable': { inputPer1M: 10.00, outputPer1M: 50.00, cacheReadPer1M: 1.00, cacheWritePer1M: 12.50, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
 };
@@ -96,6 +99,8 @@ function resolvePriceEntry(providerId, model) {
         // Keep the existing estimates for older concrete Opus generations.
         if (/^claude-opus-(?:4(?:-|$)|5$)/.test(model))
             return exports.PRICING['claude:claude-opus-5'];
+        if (/^claude-sonnet-(?:4(?:-|$)|5$)/.test(model))
+            return exports.PRICING['claude:claude-sonnet-5'];
         const family = CLAUDE_MODEL_FAMILY.exec(model);
         if (family)
             return exports.PRICING[`claude:${family[1]}`];