specrails-desktop 2.58.1 → 2.59.0

package/docs/running-pipelines.md

@@ -21,11 +21,6 @@ SpecsBoard (left)            Rails (right)
 
 A **rail** is an execution lane. Drag a spec card from the SpecsBoard onto a rail and press **▶ Play** to launch the pipeline. Rails let you organise and queue work into named lanes.
 
-Rails default to the project's primary provider. If several are installed, a
-per-rail engine selector can launch on **Claude**, **Codex**, **Gemini**, or
-**Kimi** — see [Using Kimi](kimi.md). Implement runs on every
-registered provider; Freestyle is offered by Claude and Kimi.
-
 > **One job at a time per project.** Each project has a single queue, so within a project only one rail job runs at a time; the rest queue behind it. Real parallelism is **across projects** — open two projects and their rails run independently. See [Running multiple rails](#running-multiple-rails).
 
 ## Rails
@@ -36,8 +31,6 @@ Each rail has a header with:
 - **Spec list** — the IDs of the specs assigned to this rail. Drag in more, drag out to detach. You can also use the **Move to rail** popover from a spec card; it shows a status dot per rail so you don't push work onto a busy lane.
 - **Loop picker** — the **Loop** this rail runs: a built-in (`Implement`, `SDD Quick (OpenSpec)`, or `Freestyle`) or one of your published custom loops. See [Loops](#loops).
 - **Profile picker** — which agent profile this rail uses. This only appears once the project has **at least one** profile (create them on the Agents page). When present, `No profile` runs the rail in legacy mode.
-- **Engine selector** — pick which installed provider (Claude, Codex, Gemini,
-  or Kimi) runs this rail. It renders only for multi-provider projects.
 - **Play / Stop button** — start or cancel.
 
 ### Loops
@@ -67,11 +60,6 @@ Beyond the built-ins, the **Loops** section (left sidebar, above the project lis
 
 Each run is bounded by **max iterations**, a wall-clock **timeout**, and an optional **cost cap** (USD, checked between steps). The builder also has live validation, a dry-run preview (resolve every step's exact text without spawning), import/export to JSON, and copy/paste of steps across loops. **Publish** makes a loop selectable on any rail. Built-ins are editable loops too: edit one in place and publish it to change that built-in for every rail, agent-chat launch and Companion launch that uses it (rails keep the last published version while your edit is a Draft); **Restore original** resets it and **Duplicate** copies it into a separate loop. Built-ins cannot be deleted.
 
-On the legacy traversal, Kimi runs built-in and custom loops whose graph contains AI/shell steps but no
-**Loop Decider**. A Decider's constrained `continue`/`stop` verdict is a
-pure-output action; Kimi 0.27 `-p` cannot enforce the required no-tools
-boundary, so Kimi + Decider is rejected before the loop starts.
-
 > Loop runs stream live in the Jobs view, grouped by scoped attempts. Core runs also expose their nested graph. Project role settings apply unless a deliberate launch override selects an engine for the run. Legacy profile routing and orchestrator settings remain available for older workflows.
 
 ### Pipeline phases
@@ -96,9 +84,6 @@ continue through the ordinary verification path.
 Architect ──► Developer ──► Reviewer ──► Ship
 ```
 
-Each phase is a specialised role invoked by the rail's engine (Claude, Codex,
-Gemini, or Kimi) in an isolated project worktree:
-
 | Phase | Agent | What it does |
 |-------|-------|--------------|
 | Architect | `sr-architect` | Plans the implementation |
@@ -119,17 +104,8 @@ autonomously with native tools.
 
 - **One job per spec.** If the rail has three specs, `Freestyle` launches three independent jobs.
 - **Variable cost.** Because the run is open-ended, pressing Play opens a confirmation dialog before anything spawns.
-- **Model picker.** A per-rail control uses the selected provider's model
-  catalog. Kimi offers `k3`, `kimi-for-coding`, and
-  `kimi-for-coding-highspeed`; low/high/max effort appears only for K3.
-- **Capability-gated.** Claude and Kimi advertise Freestyle. Codex and Gemini
+- **Capability-gated.** Claude advertise Freestyle. Codex
   do not. Agent profiles do not apply to Freestyle rails.
-- **Transport-aware interaction.** Claude's persistent-stdin Freestyle run is
-  a live session and waits for **Finalize**. Kimi Freestyle is agentic too,
-  but `kimi -p` has no persistent stdin transport; it follows the owned
-  one-process lifecycle and later conversations resume through a new process
-  only after Kimi has emitted a session hint. Can be disabled server-side via
-  `SPECRAILS_INTERACTIVE_JOBS=false`.
 
 You can customise the Freestyle pre-prompt per project on the [Settings page](customizing.md#freestyle-pre-prompt).
 
@@ -166,20 +142,10 @@ Two panels sit above the streaming log:
 
 Below: the full streaming log with auto-scroll, search, and copy.
 
-**Talk to the running job.** Every Claude job (and every Claude AI step in a loop run) is an interactive session by default: a chat composer sits at the bottom of the Job Detail page — and of the job modal in mission mode — so you can ask the running agent a question or steer it mid-run. Messages sent while the model is streaming queue up and run next; the job keeps following its plan. The composer shows a live `N turns · $X` line summed from each completed turn's real usage (still no estimates). Most jobs finish on their own the moment a turn completes with nothing queued — a subtle **Wrap up now** ends them early; Freestyle jobs instead wait for your explicit **Finalize**. During a loop run your messages reach the currently running AI step (between steps the composer shows a short waiting state, and **Settle this step** advances the loop). Codex, Gemini, and Kimi rail processes do not expose Claude's persistent-stdin transport; Kimi chat surfaces resume a recorded session by spawning a new `kimi -p` process. Server kill switch: `SPECRAILS_INTERACTIVE_JOBS=false`.
-
 ### Cancelling a job
 
 Click **Stop** on the rail header. The app sends `SIGTERM` to the subprocess, waits **5 s**, then `SIGKILL`.
 
-### If a rail won't launch
-
-If you pick an engine whose CLI isn't installed on your machine, the launch
-fails fast instead of starting a broken job. Install the missing provider CLI
-— see [Using Codex](codex.md), [Using Gemini](gemini.md), or
-[Using Kimi](kimi.md) — then launch again. Kimi requires the external
-authenticated `kimi` 0.27+ executable; Desktop never starts a server for it.
-
 ### Diagnostic export
 
 Visible only when [telemetry](customizing.md#telemetry) was enabled for the job. Click **Export diagnostic** in the Job Detail header to download a ZIP containing:
@@ -219,9 +185,6 @@ Pick the profile from the **rail header's profile dropdown**. It's preselected t
 
 The **`No profile`** option always exists — use it to run a rail exactly as it did pre-4.1.0. (The dropdown itself only appears once the project has at least one profile.)
 
-> **Profiles apply to providers that advertise role/profile execution.** Claude
-> and Kimi support them. Codex and Gemini currently run in legacy mode.
-
 ### Custom agents (Agent Studio)
 
 From the Agents Catalog tab, the toolbar offers three creation entry points:
@@ -256,8 +219,6 @@ Per-project bundled integrations. Click **Integrations** in the project's right
 
 Each plugin tile has:
 
-- **AI provider** — for multi-provider projects, selects the independent
-  Claude, Codex, or Kimi installation to inspect or change.
 - **Status** — `not installed`, `installed`, `orphan` (state file mentions it but `.mcp.json` doesn't), or `degraded` (verify failed).
 - **Preview install** — shows which `mcpServers` entries and agent fragments will land where, so you can sanity-check before clicking.
 - **Install** — applies the changes. Progress streams over the WebSocket (`plugin.install_progress` event).
@@ -281,11 +242,6 @@ Degraded plugins are **non-blocking** — the rail spawns anyway, but a `plugin.
 The app never wholesale rewrites these files:
 
 - `<project>/.mcp.json` — surgical merge per plugin.
-- `<project>/.kimi-code/mcp.json` — Kimi-native surgical MCP merge.
-- `<project>/CLAUDE.md`, `<project>/AGENTS.md`,
-  `<project>/GEMINI.md`, or `<project>/.kimi-code/AGENTS.md` —
-  provider-native managed instruction blocks. Provider-relative paths remain
-  independent unless two adapters explicitly declare the same path.
 - `<project>/.specrails/plugins/state.json` — install registry.
 - `<project>/.specrails/plugins/snapshots/<jobId>.json` — per-job snapshots.
 - `<project>/.claude/agents/custom-<plugin>.md` — optional fragment per plugin.
@@ -315,5 +271,4 @@ If something looks wrong:
 - [Tracking cost](tracking-cost.md) — see what each rail run is costing you.
 - [Customising the app](customizing.md) — daily budget, per-job alerts, telemetry.
 - [Using Codex](codex.md) — run rails on the Codex CLI.
-- [Using Gemini](gemini.md) — run rails on the Gemini CLI.
 - [Agent profile internals](internals/profiles.md) — for power users.

package/docs/subscription-usage.md

@@ -0,0 +1,19 @@
+# Local subscription usage
+
+The left sidebar's **Usage** section shows the currently signed-in Claude and Codex account allowance across all activity, including use outside Specrails. Each provider window has its own consumed percentage and reset time; this is separate from job tokens, billed costs and project budgets.
+
+The sidebar displays static provider cards with separate labeled quota bars. There is no floating usage panel or clickable provider card. Full reset times and data details are available in Subscription usage in global app settings. The view is always detailed, without view selectors or provider-management buttons. The collapsed sidebar shows a usage status icon. Unknown measurements are unavailable, never assumed to be zero.
+
+If neither CLI is detected, the section explains installing Claude or Codex and signing in with that CLI. It does not run usage queries for missing tools. After installation or changing login, press Refresh. An API-key login may have no subscription allowance. An incompatible Codex CLI must be updated rather than queried through a paid prompt.
+
+Updates are demand-driven while the app and a usage surface are visible. Manual refresh has a 30-second floor and provider failures can impose a longer cooldown. Data becomes stale after five minutes or a passed reset; refresh confirms the new allowance. A transient failure can retain figures from the same account with a stale label. Sign-out/auth failures clear cached figures.
+
+Credentials remain local to the server and are never sent to the frontend. The feature does not manage accounts, change provider selection, stop jobs or store usage history. Claude OAuth/Keychain availability depends on the installed CLI and OS access policy; Codex uses read-only app-server methods. Unsupported login or platform combinations show a descriptive state. Only the current host login is supported; remote/WSL account usage is not inferred.
+
+The Usage section starts collapsed. Its header toggles the provider cards with an accessible expanded state and chevron; the separate refresh button does not toggle the section.
+
+Opening the Usage section requests a refresh each time, retaining cached measurements while collection runs and respecting service cooldowns. Closing it does not request a refresh.
+
+Final placement: Usage is in the shared footer status bar in board and mission modes, removed from the left sidebar. Hover, focus or click opens the provider cards above the footer; opening requests refresh. Pointer transfer to the menu stays open, leaving dismisses after a short delay, and Escape/outside interaction closes it. Mission mode uses the minimal status bar without spend polling. This supersedes prior sidebar placement.
+
+Footer summaries show one quota per provider: account weekly when reported, otherwise the first account window, otherwise the first reported window. Values are never aggregated. The hover menu shows every individual quota and bar. There is no presentation selector or mode label.

package/docs/terminal.md

@@ -32,7 +32,6 @@ You don't have to. You can keep using iTerm/Windows Terminal/Alacritty/whatever
 
 The panel header carries three one-click shortcuts:
 
-- **Open AI CLI** (✨ Sparkles) — spins up a fresh session and types the launch command for you. On a single-provider project it launches the project's provider CLI directly (`claude`, `codex`, `gemini`, or `kimi`); on a multi-provider project it opens a small picker so you choose which CLI to start. Kimi launches the CLI itself, not `kimi server`.
 - **Open in browser** (🌐 Globe) — opens the URL from the `browserShortcutUrl` setting (default `https://specrails.dev`). Right-click it to jump to the setting and change the URL.
 - **Paste quick script** (`</>`) — writes the snippet from the `quickScript` setting (which defaults to a personalised `echo "Wake up, <username> …"` reminder, editable in Settings) into the active session. Right-click it to edit the snippet in Settings. Disabled when there's no active terminal or the snippet is empty.
 
@@ -141,4 +140,3 @@ For deeper inspection of how the panel resolves PATH at startup (relevant for Vo
 
 - [Customising the app](customizing.md) — terminal settings, themes.
 - [Getting started](getting-started.md) — registering a project.
-- [Codex](codex.md) / [Gemini](gemini.md) — setting up the CLI behind the **Open AI CLI** button on a Codex or Gemini project.

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.0",
   "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/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)