specrails-desktop 2.8.0 → 2.9.0

package/docs/platforms/windows.md

@@ -50,21 +50,28 @@ Compare the output against the matching architecture's `sha256` (`platforms["win
 The desktop app ships its own **Node** and **Git** runtimes inside the bundle, so you do **not** need to pre-install them:
 
 - `runtimes/node/{node.exe, npm.cmd, npx.cmd}`
-- `runtimes/git/cmd/git.exe`
+- `runtimes/git/cmd/git.exe` (the app probes this path first, then falls back to `runtimes/git/bin/git.exe` — PortableGit ships the real binary at `cmd/git.exe` with a redirector at `bin/git.exe`)
 
 When the bundle is present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SPECRAILS_BUNDLED_RUNTIMES_PATH`, and the embedded server prepends the bundled `node`/`git` directories to the front of `PATH` so a system install can never shadow them. If a build ships **without** the runtimes (or a partial extraction occurs), the app does not dead-end — it falls back to discovering `node`/`git` on your system `PATH` (probed with Windows `where.exe`) instead of reporting a corrupted bundle.
 
-The **provider CLIs** — **Claude Code** and **Codex** — are **never bundled**. They are always probed via your system `PATH`, in every mode. Install at least one before adding a project; the prerequisites panel blocks Add Project until one is usable.
+The **provider CLIs** — **Claude Code**, **Codex**, and **Gemini** — are **never bundled**. All three are probed via your system `PATH`, in every mode (using Windows `where.exe`). Install at least one before adding a project; the prerequisites panel blocks Add Project until one is usable. All three are enabled by default; you can roll one back with `SPECRAILS_CODEX_BETA=0` or `SPECRAILS_GEMINI_BETA=0` (each disabled only by the exact string `0`). See the per-provider setup guides: [Codex](../codex.md) and [Gemini](../gemini.md).
 
 ## Updates
 
-The desktop app self-updates via the Tauri updater plugin. It checks a GitHub Releases `latest.json` endpoint and, on Windows, applies updates with `installMode: "passive"` — the update runs with a minimal progress UI and the app relaunches into the new version. Because the installers are unsigned, an applied update may surface the same SmartScreen prompt; click **More info → Run anyway** as during the first install.
+The desktop app self-updates via the Tauri updater plugin. It checks a GitHub Releases `latest.json` endpoint and, on Windows, applies updates with `installMode: "passive"` — the update runs with a minimal progress UI and the app relaunches into the new version.
+
+Note that updates are delivered as the **MSI** (verified by an embedded **minisign** signature the updater checks before applying), not the NSIS `-setup.exe` used for first install. Because the installers are not Authenticode-signed, an applied update may still surface the same SmartScreen prompt; click **More info → Run anyway** as during the first install.
 
 ## Setup wizard
 
-When you add a project, the setup wizard runs `npx specrails-core@latest init --from-config` under the hood (the full spawn is `npx --yes --prefer-online specrails-core@latest init --yes --from-config <tempPath>`, with the app writing a temporary `install-config.yaml`). The wizard has three steps — **Configure / Install / Done**.
+When you add a project, the setup wizard runs `npx specrails-core@^4.8.0 init --from-config` under the hood (the full spawn is `npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <tempPath>`, with the app writing a temporary `install-config.yaml`). The wizard has three steps — **Configure / Install / Done**.
+
+There are two distinct version floors to be aware of:
+
+- The app **installs** `specrails-core@^4.8.0` — the major-pinned range it ships (4.8.0 is the release that adds the Gemini provider target). The exact package spec is the `CORE_PACKAGE_SPEC` constant in `server/core-package.ts`, so it stays verifiable in one place. You need internet access at install time so `npx` can resolve it.
+- The minimum it will **accept** at runtime is **specrails-core ≥ 4.1.0** — the Node-native installer floor (`MIN_NODE_NATIVE_CORE_VERSION`). Anything below that is a legacy bash/python3 installer and cannot run on Windows without WSL.
 
-This requires **specrails-core ≥ 4.1.0** — the Node-native installer floor enforced by the app (`MIN_NODE_NATIVE_CORE_VERSION`). Earlier bash/python3 installers cannot run on Windows without WSL. The app pins `@latest` on every spawn, so the constraint resolves automatically as long as you have internet access at install time.
+You can point the app at a local or linked build with the `SPECRAILS_CORE_BIN` environment variable (it overrides the `npx` spec above).
 
 Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are preserved across re-runs per the contract documented in [specrails-core's README](https://github.com/fjpulidop/specrails-core#reserved-paths).
 
@@ -76,6 +83,13 @@ Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are pres
 ## Known limitations
 
 - **Terminal panel shell**: the bottom terminal panel auto-prefers **PowerShell 7 (`pwsh.exe`)** when it is on your `PATH`, then falls back to Windows PowerShell (`powershell.exe`), and finally `COMSPEC`/`cmd.exe`. Set the `SHELL` environment variable to override the platform default with any shell you prefer. Per-session shell selection is not yet exposed in the UI.
-- **Port 4200** must be free on launch. The app binds `127.0.0.1:4200` for its API + WebSocket. If another process holds it, the app shows a native **Specrails — Port Conflict** dialog and exits.
+- **Port 4200** must be free on launch. The app binds `127.0.0.1:4200` for its API + WebSocket. If another process holds it, the app shows a native **Specrails — Port Conflict** dialog and exits. When you need to investigate, two files under `%USERPROFILE%\.specrails\` help: `desktop.log` (the embedded server's log output) and `manager.pid` (the running server's process ID).
 - **Custom window chrome**: the app uses a frameless window with a custom titlebar; the min/max/close controls are rendered by the app.
 - **Code signing**: Windows builds are unsigned in v1 (see SmartScreen above). Authenticode signing is deferred to a later release.
+
+## See also
+
+- [macOS platform guide](./macos.md) — the equivalent guide for Apple Silicon.
+- [Getting started](../getting-started.md) — first run, adding a project, the dashboard tour.
+- [Codex provider setup](../codex.md) and [Gemini provider setup](../gemini.md) — installing and configuring the provider CLIs.
+- [CLI reference](../cli.md) — driving Specrails from the command line.

package/docs/running-pipelines.md

@@ -21,7 +21,7 @@ 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 run on **Claude** by default. If your project has both providers installed, a per-rail engine selector lets you launch a rail on **Codex** instead — see [Using Codex](codex.md).
+Rails run on **Claude** by default. If your project has more than one provider installed, a per-rail engine selector lets you launch a rail on **Codex** or **Gemini** instead — see [Using Codex](codex.md) and [Using Gemini](gemini.md). Only **Ultracode** mode is Claude-only; the standard Implement and Batch pipelines run on any installed provider.
 
 > **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).
 
@@ -33,7 +33,7 @@ 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.
 - **Mode segmented control** — `Implement`, `Batch`, and (Claude rails only) `Ultra`. See [Rail modes](#rail-modes).
 - **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** — Claude vs Codex. Only renders on projects with more than one provider installed.
+- **Engine selector** — pick which installed provider (Claude, Codex, or Gemini) runs this rail. Only renders on projects with more than one provider installed.
 - **Play / Stop button** — start or cancel.
 
 ### Rail modes
@@ -54,7 +54,7 @@ The mode is a segmented control in the rail header, persisted per rail.
 Architect ──► Developer ──► Reviewer ──► Ship
 ```
 
-Each phase is a specialised Claude Code agent invoked in your project's working directory:
+Each phase is a specialised agent invoked by the rail's engine (Claude, Codex, or Gemini) in your project's working directory:
 
 | Phase | Agent | What it does |
 |-------|-------|--------------|
@@ -63,7 +63,7 @@ Each phase is a specialised Claude Code agent invoked in your project's working
 | Reviewer | `sr-reviewer` | Reviews the output |
 | Ship | (varies) | Final wrap-up: tests, commit, PR draft |
 
-The exact agent for each phase is determined by your project's agent profile. The baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`) is mandatory; routing rules in the profile can fan-out or override. The phase progress bar only renders when the command defines phases.
+In plain terms: the project's **agent profile** decides which AI agent handles each phase. The baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`) is always present; a profile's routing rules can add extra agents or swap which one runs a phase. The phase progress bar only renders when the command defines phases. For the full format, see [internals/profiles.md](internals/profiles.md).
 
 ### Ultracode mode
 
@@ -72,9 +72,10 @@ The exact agent for each phase is determined by your project's agent profile. Th
 - **One job per spec.** If the rail has three specs, `Ultra` 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 lets you pick **Haiku / Sonnet / Opus** (default Sonnet) for the Ultracode run.
-- **Claude only.** The `Ultra` segment and its model picker only appear when the rail's engine is Claude. Agent profiles don't apply to Ultracode rails.
+- **Claude only.** The `Ultra` segment and its model picker only appear when the rail's engine is Claude. Codex and Gemini rails can't run Ultracode, and agent profiles don't apply to Ultracode rails.
+- **Interactive (optional).** An `Interactive` toggle next to the `Ultra` segment turns the run into a back-and-forth session: you can chat with the running job, send follow-up prompts, and click **Finalize** when you're done. Without it, the job runs to completion on its own. (Available when the rail is idle; can be disabled server-side via `SPECRAILS_INTERACTIVE_JOBS=false`.)
 
-You can customise the Ultracode pre-prompt per project on the [Settings page](customizing.md#per-project-settings).
+You can customise the Ultracode pre-prompt per project on the [Settings page](customizing.md#ultracode-pre-prompt).
 
 ### Running multiple rails
 
@@ -102,10 +103,10 @@ Click a card to open the **Job Detail page**.
 
 ### Job Detail page
 
-Two purpose-built components above the streaming log:
+Two panels sit above the streaming log:
 
-- **`JobStatusPanel`** — header with a status icon, a live duration ticker, and an incremental counter for turns + tokens + cost (derived from streaming `assistant` events). Cost shows `—` until the authoritative `total_cost_usd` arrives at job exit.
-- **`JobTicketHeader`** — chips for every ticket the job touched (resolved by parsing the `command` and matching against the spec board). Click a chip to open the spec's detail modal over the job page without changing the route. A `+N more` collapse mode kicks in at ≥ 4 tickets.
+- **Status header** — a status icon and a live duration timer (the one genuinely live number), plus an activity line showing what the job is doing right now and a count of steps taken. Cost, turns, and tokens are deliberately **not** estimated mid-run — they show as pending and are revealed with their final, authoritative values when the job exits.
+- **Ticket header** — chips for every spec the job touched (matched from the launched command). Click a chip to open that spec's detail over the job page without leaving it. With four or more tickets, the chips collapse into a `+N more` mode you can expand.
 
 Below: the full streaming log with auto-scroll, search, and copy.
 
@@ -113,6 +114,10 @@ Below: the full streaming log with auto-scroll, search, and copy.
 
 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) or [Using Gemini](gemini.md) — then launch again. (Missing Claude or Codex returns a precise "*<provider> CLI not found*" message; missing Gemini surfaces a generic launch error today, but the result is the same — nothing spawns.)
+
 ### 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:
@@ -152,6 +157,8 @@ 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 Claude rails only.** When a rail's engine is Codex or Gemini, the run always uses legacy mode — any selected profile is ignored. Profiles are a Claude-specific feature.
+
 ### Custom agents (Agent Studio)
 
 From the Agents Catalog tab, the toolbar offers three creation entry points:
@@ -237,4 +244,5 @@ 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/terminal.md

@@ -2,6 +2,10 @@
 
 specrails-desktop ships a full-featured terminal at the bottom of the window. Toggle it with `Cmd+J` (macOS) or `Ctrl+J` (other). It's a real xterm.js with WebGL rendering, shell integration, scrollback search, file drag-and-drop, inline images, and a few quality-of-life touches you won't find in a plain terminal app.
 
+The panel opens your usual shell. On macOS/Linux it honours `$SHELL` (falling back to `/bin/zsh` when `$SHELL` is unset); on Windows it picks PowerShell (`pwsh`, then the built-in `powershell.exe`) and only falls back to `cmd.exe` as a last resort.
+
+> The terminal panel is **on by default**. To turn it off entirely, set `SPECRAILS_TERMINAL_PANEL=false` (server) or build the client with `VITE_FEATURE_TERMINAL_PANEL=false` — both are opt-out (any other value, or unset, keeps the panel on).
+
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │   Dashboard content                                         │
@@ -28,7 +32,7 @@ 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 your CLI for you. On a single-provider project it launches that provider's CLI directly (`claude` or `codex`); on a multi-provider project it opens a small picker so you choose which CLI to start.
+- **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`, or `gemini`); on a multi-provider project it opens a small picker so you choose which CLI to start.
 - **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.
 
@@ -79,7 +83,7 @@ If shell integration doesn't bootstrap — for example your `~/.zshrc` runs `exe
 Inside the Tauri desktop app, drop one or more files from Finder/Explorer onto the terminal viewport to paste their absolute paths into the active session. Paths are shell-quoted for your host platform:
 
 - macOS / Linux — POSIX single-quote
-- Windows — double-quote with `^`-escaped percent/caret (matches `cmd.exe` rules)
+- Windows — PowerShell single-quote (the panel's default Windows shell is PowerShell, where single-quoted strings are literal, so this is injection-safe)
 
 In a plain browser context this is a silent no-op — the browser doesn't expose `File.path`.
 
@@ -117,9 +121,10 @@ Render mode `auto` picks WebGL when the WebView exposes WebGL2; on `webglcontext
 ## Limits and edge cases
 
 - **Sessions per project** — hard cap of 10.
-- **Closing a project** — kills all its sessions immediately.
+- **Closing a project** — kills all its sessions (SIGTERM, then SIGKILL after a short grace).
 - **Window close / quit** — graceful: SIGTERM, 2 s grace, SIGKILL.
 - **Cmd+J inside an open Dialog** — ignored. The panel won't toggle on top of a modal.
+- **Failed spawn** — if a new session dies within ~1.5 s of opening (for example the host is out of file descriptors), the panel surfaces a concrete reason (e.g. "out of file descriptors") instead of leaving a blank pane.
 
 ## Diagnostics
 
@@ -136,3 +141,4 @@ 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,6 +1,6 @@
 # Tracking cost
 
-specrails-desktop records every AI CLI invocation it spawns — both Claude and Codex — and surfaces the totals on one Analytics page per project. This guide walks through what's tracked, what's not, and how to read the dashboard.
+specrails-desktop records every AI CLI invocation it spawns — Claude, Codex, and Gemini — and surfaces the totals on one Analytics page per project. This guide walks through what's tracked, what's not, and how to read the dashboard.
 
 ## What gets tracked
 
@@ -15,22 +15,27 @@ 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: provider (Claude or Codex), model, status, started/finished timestamps, duration (wall clock + API-only), tokens (in / out / cache read / cache create), total USD cost, turn count, and — when applicable — the ticket and conversation IDs it touched.
+Each invocation row carries: provider (Claude, Codex, or Gemini), model, status, started/finished timestamps, duration (wall clock + API-only), tokens (in / out / cache read / cache create), total USD cost, turn count, and — when applicable — the ticket and conversation IDs it touched.
 
 > Cost averages exclude `failed`/`aborted` rows, but those rows still count toward the total run count and the failure rate.
 
-## Claude vs Codex cost
+## Authoritative vs estimated cost
 
-Claude cost is **provider-billed and authoritative** — the figure comes straight from the CLI.
+Whether a cost figure is exact depends on the provider's CLI, not on which provider you picked:
 
-Codex has no native cost field, so the app **estimates** its cost from a local rate-card (`server/pricing.ts`). Estimated rows are flagged: they render with a `~` tilde in the raw table and feed an "includes ~$X estimated" footnote in the Hero. On multi-provider projects, a **Provider breakdown** card splits spend by engine so you can see authoritative vs estimated at a glance.
+- **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/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.
 
 ## What's NOT tracked (intentionally)
 
 - **Sidebar chat** — the general-purpose chat panel in the right sidebar. It spawns an AI process 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 (e.g. the Anthropic console for Claude) is the source of truth.
+If you want the absolute total of what an engine has cost you, your provider's own console is the source of truth — the Anthropic console for Claude, the OpenAI dashboard for Codex, and Google AI Studio / Cloud billing for Gemini.
 
 ## The Analytics page
 
@@ -40,7 +45,7 @@ Open **Analytics** from the project right sidebar.
 
 - **Period** — `7d`, `30d`, `90d`, or `All`. (There's no 24-hour or custom-range option here — the custom calendar range lives on Desktop Analytics, below.)
 - **Surface** — chips for `All` plus each of the six surfaces (Jobs, Explore, Quick, Refine, SMASH, File summaries). All are included by default; toggle chips to narrow the view.
-- **Engine** — provider chips (Claude / Codex) that appear **only on multi-provider projects**, letting you filter by engine.
+- **Engine** — one chip per installed provider (Claude, Codex, Gemini) plus `All`. These appear **only on multi-provider projects** (more than one engine installed) and let you filter spend by engine.
 
 The period and surface filters are URL-synced, so you can share or bookmark a view.
 
@@ -57,13 +62,13 @@ When the project has zero invocations in the period (e.g. you just started), the
 
 ### Provider breakdown
 
-On multi-provider projects, a dedicated card splits total spend between Claude and Codex. It's hidden on single-provider projects.
+On multi-provider projects, a dedicated card splits total spend across the project's installed engines (Claude, Codex, Gemini) — it's data-driven, so it renders for any combination of more than one provider. Each engine's row marks an all-estimated total with a `~` tilde. It's hidden on single-provider projects.
 
 ### Daily stacked timeline
 
-A daily bar chart for the period, stacked by surface. Days with zero activity are zero-filled so the x-axis stays regular.
+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.
 
-Surface colours are consistent across the whole page:
+Surface colours are consistent wherever a surface appears across the page:
 
 - `job` → blue (`accent-info`)
 - `quick-spec` → purple (`accent-secondary`)
@@ -152,4 +157,5 @@ 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.
+- [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).

package/package.json

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

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

@@ -15,6 +15,7 @@ const agent_generator_1 = require("./agent-generator");
 const ai_invocations_1 = require("./ai-invocations");
 const result_event_1 = require("./result-event");
 const spawn_lifecycle_1 = require("./spawn-lifecycle");
+const workspace_resolution_1 = require("./workspace-resolution");
 const providers_1 = require("./providers");
 const agent_refine_db_1 = require("./agent-refine-db");
 const CUSTOM_PREFIX = /^custom-[a-z0-9][a-z0-9-]*$/;
@@ -174,14 +175,23 @@ class AgentRefineManager {
     // ─── Private ──────────────────────────────────────────────────────────────
     _agentFile(agentId) {
         // Per-provider on-disk layout:
-        //   claude → <project>/.claude/agents/<agentId>.md
-        //   codex  → <project>/.codex/skills/<agentId>/SKILL.md
+        //   claude → <root>/.claude/agents/<agentId>.md
+        //   codex  → <root>/.codex/skills/<agentId>/SKILL.md
         // Future providers add their own branch via the adapter; the projectDir
         // is already provider-aware.
+        //
+        // Relocate-artifacts: custom-* agents are materialized by core into the
+        // WORKSPACE when the project is relocated (same place the rails load them
+        // from). Reading/writing `<project.path>/<providerDir>/agents` would touch a
+        // stale repo copy the rails never see — and this path WRITES the refined
+        // agent. Resolve through the gate so reads + writes hit the same tree the
+        // rails consume. Legacy projects are byte-identical (root === project.path).
+        const exec = (0, workspace_resolution_1.resolveProjectExecution)({ path: this._projectPath });
+        const root = exec.relocated && exec.workspaceDir ? exec.workspaceDir : this._projectPath;
         if (this._adapter.id === 'codex') {
-            return path_1.default.join(this._projectPath, this._adapter.projectDirName, 'skills', agentId, 'SKILL.md');
+            return path_1.default.join(root, this._adapter.projectDirName, 'skills', agentId, 'SKILL.md');
         }
-        return path_1.default.join(this._projectPath, this._adapter.projectDirName, 'agents', `${agentId}.md`);
+        return path_1.default.join(root, this._adapter.projectDirName, 'agents', `${agentId}.md`);
     }
     _currentVersion(agentId) {
         const row = this._db
@@ -224,11 +234,16 @@ class AgentRefineManager {
         // Spawn / stream / settlement is owned by the shared spawn-lifecycle; the
         // refine-specific draft buffering, accounting, validation and history all
         // stay here unchanged.
+        // Relocate-artifacts gate: spawn from the workspace (with SPECRAILS_REPO_DIR)
+        // when relocated, else cwd = project.path + empty env (byte-identical legacy).
+        const refineExec = (0, workspace_resolution_1.resolveProjectExecution)({ path: this._projectPath });
+        const refineEnv = refineExec.relocated ? { ...process.env, ...refineExec.env } : undefined;
         const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
             adapter: this._adapter,
             action,
             buildOpts: { prompt, model: refineModel, sessionId: session.session_id ?? undefined },
-            cwd: this._projectPath,
+            cwd: refineExec.cwd,
+            env: refineEnv,
             onSpawn: (child) => this._activeProcesses.set(refineId, child),
             onSpawnError: (err) => { spawnState.err = err; },
             onEvent: (ev) => {