specrails-desktop 2.7.0 → 2.9.0

package/server/dist/providers/gemini-agent-ack.js

@@ -0,0 +1,65 @@
+"use strict";
+// Gemini headless subagent pre-acknowledgment.
+//
+// gemini 0.46+ DISCOVERS `<project>/.gemini/agents/*.md` but only ENABLES a
+// project's custom subagents after an interactive "New Agents Discovered →
+// Acknowledge and Enable" prompt. That prompt never fires in headless
+// (`gemini -p`) spawns — which is how the desktop runs every rail — so
+// `invoke_agent sr-architect` returns "Subagent not found" and the implement
+// orchestrator silently falls back to a generic agent (the specialised
+// architect/developer/reviewer personas never run in isolation).
+//
+// specrails-core writes the acknowledgment file at install time; this is the
+// defence-in-depth copy the desktop runs right before a gemini rail spawn, so a
+// project installed with an older core (or whose agents changed since install)
+// is still trusted headless. The file gemini reads is
+// `~/.gemini/acknowledgments/agents.json`, shaped
+//   { [projectRoot]: { [agentName]: <sha256-hex of the agent .md file> } }
+// where the hash is sha256 of the FULL agent markdown file (verified empirically
+// against gemini 0.47). Entries are MERGED so other projects (and other agents)
+// survive. Best-effort — callers swallow any error; a failure only means the
+// agents need the one-time interactive acknowledge.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acknowledgeGeminiProjectAgents = acknowledgeGeminiProjectAgents;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+function ackFilePath() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.gemini', 'acknowledgments', 'agents.json');
+}
+/**
+ * Pre-acknowledge every `<projectPath>/.gemini/agents/*.md` so gemini loads them
+ * in headless mode. No-op when the project has no `.gemini/agents` dir or no
+ * agent files. The `projectPath` is the key gemini uses (the spawn cwd / repo
+ * root), matching what `specrails-core` writes at install.
+ */
+function acknowledgeGeminiProjectAgents(projectPath) {
+    const agentsDir = (0, path_1.join)(projectPath, '.gemini', 'agents');
+    if (!(0, fs_1.existsSync)(agentsDir))
+        return;
+    const agentFiles = (0, fs_1.readdirSync)(agentsDir).filter((f) => f.endsWith('.md') && !f.startsWith('_'));
+    if (agentFiles.length === 0)
+        return;
+    const ackPath = ackFilePath();
+    let store = {};
+    if ((0, fs_1.existsSync)(ackPath)) {
+        try {
+            const parsed = JSON.parse((0, fs_1.readFileSync)(ackPath, 'utf8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                store = parsed;
+            }
+        }
+        catch {
+            // Corrupt/unreadable file — start fresh rather than crash the spawn.
+        }
+    }
+    const projectEntry = { ...(store[projectPath] ?? {}) };
+    for (const file of agentFiles) {
+        const content = (0, fs_1.readFileSync)((0, path_1.join)(agentsDir, file), 'utf8');
+        projectEntry[file.slice(0, -3)] = (0, crypto_1.createHash)('sha256').update(content).digest('hex');
+    }
+    store[projectPath] = projectEntry;
+    (0, fs_1.mkdirSync)((0, path_1.join)((0, os_1.homedir)(), '.gemini', 'acknowledgments'), { recursive: true });
+    (0, fs_1.writeFileSync)(ackPath, `${JSON.stringify(store, null, 2)}\n`);
+}

package/server/dist/queue-manager.js

@@ -28,6 +28,10 @@ const interactive_job_session_1 = require("./interactive-job-session");
 const attachment_manager_1 = require("./attachment-manager");
 const ticket_store_1 = require("./ticket-store");
 const binary_probe_1 = require("./binary-probe");
+const workspace_resolution_1 = require("./workspace-resolution");
+const framework_manager_1 = require("./framework-manager");
+const openspec_shim_1 = require("./openspec-shim");
+const artifact_registry_1 = require("./artifact-registry");
 // ─── Telemetry env helpers ────────────────────────────────────────────────────
 /** Build the OTEL environment variable block for a spawned claude process.
  * Extracted as a pure function so it is unit-testable without a full spawn. */
@@ -156,6 +160,13 @@ class QueueManager {
     /** Pre-spawn working-tree snapshot refs keyed by jobId — read at exit time
      *  by the Code-Explorer provenance hook. Cleared on job exit. */
     _snapshotRefs;
+    /** Per-job resolved execution context (relocate-artifacts gate), captured at
+     *  spawn time so `_onJobExit`'s provenance hook uses the SAME repoDir the
+     *  snapshot used (= project.path, never the workspace). Cleared on job exit. */
+    _jobExecution;
+    /** Per-job openspec PATH shim dir (relocated claude rails only). Cleaned up on
+     *  job exit. In-memory map of jobId → shim dir. */
+    _openspecShims = new Map();
     /** Pending per-job interactive flag keyed by jobId — read at spawn time.
      *  In-memory only (mirrors _jobModelSelection). */
     _jobInteractiveSelection;
@@ -190,6 +201,7 @@ class QueueManager {
         this._jobProviderSelection = new Map();
         this._jobModelSelection = new Map();
         this._snapshotRefs = new Map();
+        this._jobExecution = new Map();
         this._jobInteractiveSelection = new Map();
         this._interactiveSessions = new Map();
         const envTimeout = process.env.WM_ZOMBIE_TIMEOUT_MS !== undefined
@@ -261,6 +273,8 @@ class QueueManager {
         this._interactiveSessions.clear();
         // Release any per-job provenance snapshots so teardown leaves no map entries.
         this._snapshotRefs.clear();
+        this._jobExecution.clear();
+        this._openspecShims.clear();
         // Drop the DB reference last so any in-flight 'close' callback sees null
         // and skips all DB work via the existing `if (this._db)` guards.
         this._db = null;
@@ -522,7 +536,7 @@ class QueueManager {
         if (ticketIds.length === 0)
             return '';
         try {
-            const store = (0, ticket_store_1.readStore)((0, ticket_store_1.resolveTicketStoragePath)(this._cwd));
+            const store = (0, ticket_store_1.readStore)(this._resolveTicketsPath());
             const sections = [];
             for (const ticketId of ticketIds) {
                 const storeAttachmentIds = new Set((store.tickets[String(ticketId)]?.attachments ?? []).map((attachment) => attachment.id));
@@ -563,7 +577,7 @@ class QueueManager {
         const specs = [];
         if (this._cwd) {
             try {
-                const store = (0, ticket_store_1.readStore)((0, ticket_store_1.resolveTicketStoragePath)(this._cwd));
+                const store = (0, ticket_store_1.readStore)(this._resolveTicketsPath());
                 for (const ticketId of ticketIds) {
                     const ticket = store.tickets[String(ticketId)];
                     if (!ticket)
@@ -634,6 +648,46 @@ class QueueManager {
         }
         return this._adapter;
     }
+    /**
+     * Resolve the relocate-artifacts execution context for this manager's project.
+     * The gate: relocated only when a registry entry exists AND core has populated
+     * the workspace; otherwise legacy (cwd = project.path, empty env) — preserving
+     * byte-identical behaviour for every existing in-repo project. Falls back to a
+     * legacy resolution rooted at `this._cwd` when slug/cwd are unavailable
+     * (non-Super contexts / tests that construct the manager without a slug).
+     */
+    _resolveExecution() {
+        const repoDir = this._cwd ?? process.cwd();
+        if (!this._projectSlug || !this._cwd) {
+            return {
+                relocated: false,
+                cwd: repoDir,
+                repoDir,
+                workspaceDir: null,
+                ticketsPath: path_1.default.join(repoDir, '.specrails', 'local-tickets.json'),
+                backlogConfigPath: path_1.default.join(repoDir, '.specrails', 'backlog-config.json'),
+                profilesDir: path_1.default.join(repoDir, '.specrails', 'profiles'),
+                pluginsStateDir: path_1.default.join(repoDir, '.specrails', 'plugins'),
+                fileSummariesDir: path_1.default.join(repoDir, '.specrails', 'file-summaries'),
+                specrailsDir: path_1.default.join(repoDir, '.specrails'),
+                stateDir: path_1.default.join(repoDir, '.claude'),
+                env: {},
+            };
+        }
+        return (0, workspace_resolution_1.resolveProjectExecution)({ slug: this._projectSlug, path: this._cwd });
+    }
+    /**
+     * Resolve the local-tickets.json path honouring the relocate-artifacts gate.
+     * Relocated ⇒ the registry entry's ticketsPath (workspace). Legacy ⇒
+     * `resolveTicketStoragePath(this._cwd)` which preserves the
+     * integration-contract.json custom-storagePath behaviour for existing repos.
+     */
+    _resolveTicketsPath() {
+        const exec = this._resolveExecution();
+        if (exec.relocated)
+            return exec.ticketsPath;
+        return (0, ticket_store_1.resolveTicketStoragePath)(this._cwd ?? process.cwd());
+    }
     /**
      * Spawn an interactive ultracode session. The job row is created with the
      * `interactive` flag set; the resident child runs the first turn (the
@@ -687,6 +741,13 @@ class QueueManager {
         // Interactive jobs skip provenance, but a defensive delete keeps the map
         // clean if a snapshot was ever recorded for this id.
         this._snapshotRefs.delete(jobId);
+        // Clean up the per-job openspec PATH shim (relocated claude rails only).
+        const shim = this._openspecShims.get(jobId);
+        if (shim) {
+            this._openspecShims.delete(jobId);
+            if (this._projectSlug)
+                (0, openspec_shim_1.removeOpenspecShim)(this._projectSlug, jobId, (0, artifact_registry_1.resolveHome)());
+        }
         if (this._disposed)
             return;
         const job = this._jobs.get(jobId);
@@ -785,6 +846,13 @@ class QueueManager {
         // primary; everything in this spawn (binary, argv, model, profile, OTEL,
         // plugins, result parsing, ai_invocations.provider) flows from `adapter`.
         const adapter = this._resolveJobAdapter(jobId);
+        // Relocate-artifacts gate: resolve cwd/repoDir/env for this spawn. Legacy
+        // projects get cwd = project.path + empty env (byte-identical to today);
+        // relocated projects get cwd = workspace + SPECRAILS_REPO_DIR. Captured per
+        // job so the post-exit provenance hook uses the SAME repoDir.
+        const execution = this._resolveExecution();
+        this._jobExecution.set(jobId, execution);
+        const spawnCwd = execution.cwd;
         job.status = 'running';
         job.startedAt = new Date().toISOString();
         job.queuePosition = null;
@@ -875,10 +943,17 @@ class QueueManager {
             : adapter.id === 'claude' && this._db
                 ? (0, db_1.getProjectSettings)(this._db).orchestratorModel
                 : (this._resolvedModel ?? adapter.defaultModel());
+        // Relocate-artifacts: when relocated, claude is spawned from the workspace
+        // so add `--add-dir <repoDir>` so its tools can still reach repo files by
+        // absolute path. (gemini/codex get env-only tweaks at spawn time below.)
+        const railExtraArgs = execution.relocated && adapter.id === 'claude'
+            ? ['--add-dir', execution.repoDir]
+            : undefined;
         const args = adapter.buildArgs('rail-job', {
             prompt: railPrompt,
             systemPrompt: systemAppend || undefined,
             model: railModel,
+            extraArgs: railExtraArgs,
         });
         // Resolve agent profile (if any) and snapshot per-job before spawn.
         // Super mode only (projectId + projectSlug + cwd all present).
@@ -894,11 +969,13 @@ class QueueManager {
             try {
                 const selection = this._jobProfileSelection.get(jobId); // undefined|null|string
                 this._jobProfileSelection.delete(jobId);
-                const coreSupports = projectSupportsProfiles(this._cwd);
+                // When relocated, core + `.specrails/profiles` live in the workspace
+                // (execution.cwd); legacy reads from the repo (execution.cwd === repo).
+                const coreSupports = projectSupportsProfiles(execution.cwd);
                 if (selection !== null && coreSupports) {
                     // selection is string (explicit) or undefined (default resolution)
                     const { resolveProfile, snapshotForJob, persistJobProfile, } = require('./profile-manager');
-                    const resolved = resolveProfile(this._cwd, selection ?? undefined, adapter.id);
+                    const resolved = resolveProfile(execution.cwd, selection ?? undefined, adapter.id);
                     if (resolved) {
                         profileSnapshotPath = snapshotForJob(this._projectSlug, jobId, resolved);
                         profileName = resolved.name;
@@ -921,12 +998,22 @@ class QueueManager {
         // gets signals synthesised by the codex-otel-bridge attached below.
         let spawnEnv = process.env;
         const telemetryEnabled = !!(this._projectId && this._db && (0, db_1.getProjectSettings)(this._db).pipelineTelemetryEnabled);
+        // Resolve the framework version ONCE at spawn time — `framework/current`
+        // is read from `~/.specrails/framework/current`. A concurrent atomic swap
+        // (FrameworkManager.swapCurrent) does not disturb this job: we captured the
+        // version here and the per-job snapshot resolved its handles from this
+        // value. GATED on `execution.relocated`: a LEGACY (in-repo) job does NOT
+        // assemble from `framework/current`, so stamping it with a sibling project's
+        // materialized framework version would be wrong telemetry. Null otherwise.
+        const frameworkVersion = execution.relocated ? (0, framework_manager_1.readCurrentFrameworkVersion)() : null;
         if (telemetryEnabled && adapter.capabilities.nativeOtelEnv && this._projectId) {
             const extra = {};
             if (profileName)
                 extra['specrails.profile_name'] = profileName;
             if (profileName)
                 extra['specrails.profile_schema_version'] = '1';
+            if (frameworkVersion)
+                extra['specrails.framework_version'] = frameworkVersion;
             spawnEnv = {
                 ...process.env,
                 ...buildTelemetryEnv(jobId, this._projectId, this._desktopPort, extra),
@@ -952,7 +1039,8 @@ class QueueManager {
         if (adapter.mcpRegistration === 'project-json' && this._projectId && this._projectSlug && this._cwd) {
             try {
                 const { resolvePluginsForSpawn, snapshotPluginsForJob } = require('./plugins/rail-integration');
-                const resolution = await resolvePluginsForSpawn(this._cwd, this._projectId, jobId);
+                // Relocated ⇒ `.mcp.json`/plugin state live in the workspace (execution.cwd).
+                const resolution = await resolvePluginsForSpawn(execution.cwd, this._projectId, jobId);
                 pluginActive = resolution.active;
                 pluginDegraded = resolution.degraded;
                 if (pluginActive.length > 0 || pluginDegraded.length > 0) {
@@ -987,6 +1075,14 @@ class QueueManager {
             const settings = (0, db_1.getProjectSettings)(this._db);
             if (settings.pipelineTelemetryEnabled && (pluginActive.length > 0 || pluginDegraded.length > 0)) {
                 const extra = {};
+                // Re-thread the resolved framework version (this block rebuilds the
+                // whole telemetry env, so it must carry the same attr as the first one).
+                if (frameworkVersion)
+                    extra['specrails.framework_version'] = frameworkVersion;
+                if (profileName)
+                    extra['specrails.profile_name'] = profileName;
+                if (profileName)
+                    extra['specrails.profile_schema_version'] = '1';
                 if (pluginActive.length > 0) {
                     extra['specrails.plugins.active'] = JSON.stringify(pluginActive.map((p) => p.name));
                     extra['specrails.plugins.versions'] = JSON.stringify(Object.fromEntries(pluginActive.map((p) => [p.name, p.version])));
@@ -1000,6 +1096,44 @@ class QueueManager {
                 };
             }
         }
+        // Provider-specific filesystem prep before a headless rail spawn. Gemini
+        // uses this to pre-acknowledge the project's custom subagents so they load
+        // in `gemini -p` mode (else invoke_agent reports "Subagent not found" and the
+        // orchestrator silently falls back to a generic agent). No-op for claude/codex.
+        // Runs in the SPAWN cwd (workspace when relocated) — gemini acks the
+        // project's subagents where it will actually discover them.
+        try {
+            adapter.prepareHeadlessSpawn?.(spawnCwd);
+        }
+        catch (err) {
+            /* c8 ignore next -- best-effort prep; a failure is non-fatal */
+            console.warn(`[queue-manager] headless-spawn prep failed: ${err.message}`);
+        }
+        // ─── Relocate-artifacts spawn env ──────────────────────────────────────
+        // Merge SPECRAILS_REPO_DIR (+ workspace/tickets/state/etc.) so stage-3
+        // `${SPECRAILS_REPO_DIR:-.}` re-pointing drives source/openspec/git I/O back
+        // into the repo. Per provider: gemini trusts the workspace cwd; codex gets
+        // NO CODEX_HOME override (all-or-nothing incl. auth → breaks the rail) and
+        // relies on cwd-based discovery from the workspace. Legacy ⇒ empty env, no-op.
+        if (execution.relocated) {
+            spawnEnv = { ...spawnEnv, ...execution.env };
+            if (adapter.id === 'gemini') {
+                spawnEnv = { ...spawnEnv, GEMINI_CLI_TRUST_WORKSPACE: 'true' };
+            }
+            // openspec PATH shim (claude rails only): prepend a per-job shim dir that
+            // re-points every BARE `openspec` call at the repo working tree, so a
+            // skill- or un-wrapped-template-driven `openspec <verb>` from the workspace
+            // cwd still operates on the repo's OpenSpec project (see openspec-shim.ts).
+            // claude is the only adapter that runs the openspec-backed sr-* rails;
+            // gemini/codex skill scaffolds carry their own repo-dir wrapping.
+            if (adapter.id === 'claude' && this._projectSlug) {
+                const shimDir = (0, openspec_shim_1.ensureOpenspecShim)(this._projectSlug, jobId, (0, artifact_registry_1.resolveHome)());
+                if (shimDir) {
+                    this._openspecShims.set(jobId, shimDir);
+                    spawnEnv = { ...spawnEnv, PATH: (0, openspec_shim_1.prependShimToPath)(spawnEnv.PATH, shimDir) };
+                }
+            }
+        }
         // ─── Interactive ultracode branch ──────────────────────────────────────
         // When the launch requested interactive mode AND the command is ultracode
         // AND the adapter supports persistent stdin (claude), hand off to a resident
@@ -1015,16 +1149,20 @@ class QueueManager {
                 prompt: '',
                 systemPrompt: systemAppend || undefined,
                 model: railModel,
+                extraArgs: railExtraArgs,
             });
-            this._startInteractiveJob(jobId, job, adapter, { binary, args: interactiveArgs, cwd: this._cwd, env: spawnEnv }, railPrompt);
+            this._startInteractiveJob(jobId, job, adapter, { binary, args: interactiveArgs, cwd: spawnCwd, env: spawnEnv }, railPrompt);
             return;
         }
         // Code-Explorer pre-spawn snapshot. Captures the working-tree state via
         // `git stash create --include-untracked` so the post-exit hook can diff
         // against it. Gated by SPECRAILS_CODE_EXPLORER — when off, no-op.
-        if ((0, feature_flags_1.isCodeExplorerEnabled)() && this._cwd) {
+        // CRITICAL: snapshot the REPO working tree (execution.repoDir), never the
+        // workspace — else a relocated job would diff an empty workspace and silently
+        // record zero "touched by AI" files.
+        if ((0, feature_flags_1.isCodeExplorerEnabled)()) {
             try {
-                const snap = (0, file_provenance_1.snapshotWorkingTree)(this._cwd);
+                const snap = (0, file_provenance_1.snapshotWorkingTree)(execution.repoDir);
                 this._snapshotRefs.set(jobId, snap);
             }
             catch (err) {
@@ -1035,7 +1173,7 @@ class QueueManager {
         const child = (0, cli_prompt_1.spawnAiCli)(binary, args, {
             env: spawnEnv,
             stdio: ['ignore', 'pipe', 'pipe'],
-            cwd: this._cwd,
+            cwd: spawnCwd,
         });
         this._activeProcess = child;
         this._activeJobId = jobId;
@@ -1224,6 +1362,12 @@ class QueueManager {
         // stash commit it references is dangling and git-GC'd on its own).
         const snapshot = this._snapshotRefs.get(jobId);
         this._snapshotRefs.delete(jobId);
+        // Relocate-artifacts: the repo dir this job snapshotted against (= repoDir,
+        // never the workspace). Falls back to this._cwd for jobs spawned before this
+        // map existed (e.g. restored-from-db) so provenance still targets the repo.
+        const jobExecution = this._jobExecution.get(jobId);
+        this._jobExecution.delete(jobId);
+        const provenanceRepoDir = jobExecution?.repoDir ?? this._cwd;
         // A3: release the active slot for THIS job before any early return, so a
         // disposed/unknown-job exit can never leave the slot reserved (which would
         // wedge the queue). Guarded by identity in case a stale exit fires late.
@@ -1328,11 +1472,11 @@ class QueueManager {
             // the pre-spawn snapshot and inserts one row per touched path. Gated by
             // SPECRAILS_CODE_EXPLORER (re-checked at each completion so the flag can
             // be flipped off mid-session without leaving partial writes).
-            if ((0, feature_flags_1.isCodeExplorerEnabled)() && this._cwd && this._projectId) {
+            if ((0, feature_flags_1.isCodeExplorerEnabled)() && provenanceRepoDir && this._projectId) {
                 const ref = snapshot?.ref ?? '';
                 try {
-                    const diff = (0, file_provenance_1.diffAgainstSnapshot)(this._cwd, ref, snapshot?.untracked, snapshot?.headSha);
-                    const patches = (0, file_provenance_1.collectDiffPatches)(this._cwd, ref, diff, snapshot?.headSha);
+                    const diff = (0, file_provenance_1.diffAgainstSnapshot)(provenanceRepoDir, ref, snapshot?.untracked, snapshot?.headSha);
+                    const patches = (0, file_provenance_1.collectDiffPatches)(provenanceRepoDir, ref, diff, snapshot?.headSha);
                     if (diff.length > 50) {
                         console.warn(`[provenance.large_job] job=${jobId} files=${diff.length}`);
                     }

package/server/dist/setup-manager.js

@@ -20,6 +20,11 @@ const win_spawn_1 = require("./util/win-spawn");
 const setup_prerequisites_1 = require("./setup-prerequisites");
 const core_package_1 = require("./core-package");
 const providers_1 = require("./providers");
+const artifact_registry_1 = require("./artifact-registry");
+const install_config_path_1 = require("./install-config-path");
+const bundled_core_1 = require("./bundled-core");
+const bundled_openspec_1 = require("./bundled-openspec");
+const framework_manager_1 = require("./framework-manager");
 /**
  * specrails-core's installer (Node-native from v4.2.0 onward, bash
  * prior) always scaffolds into `.claude/` regardless of which AI
@@ -75,6 +80,45 @@ function spawnCoreInit(args, cwd) {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
 }
+/**
+ * Spawn the BUNDLED specrails-core `init` (offline framework + assemble; openspec
+ * is the only network step). Runs `node <bundled-cli> init <args>` with
+ * `SPECRAILS_CORE_SCRIPT_DIR` pointed at the bundle so core's template/command
+ * sources resolve from the app bundle, NOT a global install or npm registry. The
+ * framework was already materialized by FrameworkManager.materialize() (idempotent
+ * — core's ensureFramework skips re-materialization), so this call only assembles
+ * the workspace by symlink + runs openspec init.
+ *
+ * Returns null when no bundled core is present (caller falls back to spawnCoreInit).
+ */
+function spawnBundledCoreInit(args, cwd) {
+    const cli = (0, bundled_core_1.getBundledCoreCli)();
+    const coreRoot = (0, bundled_core_1.getBundledCoreRoot)();
+    if (!cli || !coreRoot)
+        return null;
+    const fullArgs = [cli, 'init', ...args];
+    const env = { ...process.env, SPECRAILS_CORE_SCRIPT_DIR: coreRoot };
+    // Bundled openspec (offline) — the LAST network step of project-add. When the
+    // app ships @fission-ai/openspec, point specrails-core's `installOpenSpecProject`
+    // at the bundled CLI and the SAME node we run the bundled core with. Tauri
+    // strips exec bits from bundled resources and the openspec CLI is a node script,
+    // so it MUST be invoked as `node <cli> init …` — hence we set BOTH the BIN and
+    // the NODE env (specrails-core's buildOpenSpecInvocation form 1). When absent we
+    // leave them unset → core falls back to `npx @fission-ai/openspec` (still works
+    // online). Bundled core + bundled openspec ⇒ project-add is FULLY OFFLINE.
+    const openspecCli = (0, bundled_openspec_1.getBundledOpenspecCli)();
+    if (openspecCli) {
+        env.SPECRAILS_OPENSPEC_BIN = openspecCli;
+        env.SPECRAILS_OPENSPEC_NODE = process.execPath;
+    }
+    console.log(`[SetupManager] spawning BUNDLED core: ${process.execPath} ${fullArgs.join(' ')} (cwd=${cwd})` +
+        (openspecCli ? ' [bundled openspec: offline]' : ' [openspec: npx fallback]'));
+    return (0, win_spawn_1.spawnCli)(process.execPath, fullArgs, {
+        cwd,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
 // H19: hard cap on the runtime probe. `npx --yes --prefer-online
 // <CORE_PACKAGE_SPEC> version` does a network round-trip to the npm
 // registry, and spawnSync blocks the single event loop — without a timeout a
@@ -120,8 +164,8 @@ function writeSpawnInstallConfig(projectId, yamlText) {
     (0, fs_1.writeFileSync)(tempPath, yamlText, 'utf-8');
     return tempPath;
 }
-function readInstallConfig(projectPath) {
-    const configPath = (0, path_1.join)(projectPath, '.specrails', 'install-config.yaml');
+function readInstallConfig(project) {
+    const configPath = (0, install_config_path_1.installConfigPath)(project);
     try {
         const text = (0, fs_1.readFileSync)(configPath, 'utf-8');
         const tierMatch = text.match(/^tier:\s*(\w+)/m);
@@ -591,14 +635,33 @@ class SetupManager {
         this._projectNames = new Map();
     }
     // ─── Full Install: TUI installer (npx specrails-core) ────────────────────────
-    startInstall(projectId, projectPath) {
+    startInstall(projectId, projectPath, projectSlug) {
         if (this._installProcesses.has(projectId)) {
             console.warn(`[SetupManager] install already running for ${projectId}`);
             return;
         }
-        const configPath = (0, path_1.join)(projectPath, '.specrails', 'install-config.yaml');
+        // Relocate-artifacts: ensure the shared registry entry exists (slug
+        // agreement) BEFORE core's `init` runs, so core resolves its workspace from
+        // the registry and installs the relocated artifacts under desktop's slug.
+        // addProject already mirrors the entry; this is belt-and-suspenders for the
+        // (rare) case where the project was registered before the mirror existed.
+        // Wrapped so a registry write failure never blocks install (core then
+        // installs in-repo and the project simply stays legacy — gate-safe).
+        if (projectSlug) {
+            try {
+                (0, artifact_registry_1.mirrorProjectEntry)({ repoPath: projectPath, slug: projectSlug, desktopProjectId: projectId });
+            }
+            catch (err) {
+                console.warn(`[SetupManager] registry mirror before install failed (non-fatal): ${err.message}`);
+            }
+        }
+        // Relocate-artifacts: the install config lives in the per-project HOME dir
+        // (NOT the repo). `--from-config` accepts any path, so the spawn below points
+        // core at the relocated location.
+        const installProject = { slug: projectSlug, path: projectPath };
+        const configPath = (0, install_config_path_1.installConfigPath)(installProject);
         const hasConfig = (0, fs_1.existsSync)(configPath);
-        const parsedConfig = hasConfig ? readInstallConfig(projectPath) : null;
+        const parsedConfig = hasConfig ? readInstallConfig(installProject) : null;
         const tier = parsedConfig?.tier ?? 'full';
         this._projectTiers.set(projectId, tier);
         // Pull provider out of the just-written install-config.yaml so the
@@ -628,24 +691,54 @@ class SetupManager {
             });
             return;
         }
-        const probe = probeCoreRuntimeVersion(projectPath);
-        if (!probe.ok) {
-            this._broadcast({
-                type: 'setup_error',
-                projectId,
-                error: `Failed to verify specrails-core runtime before install: ${probe.error ?? 'unknown error'}`,
-            });
-            return;
+        // ─── Bundled-core fast path (offline framework) ──────────────────────────
+        // When the app ships specrails-core, materialize the versioned framework
+        // ONCE (instant/offline) and run the BUNDLED core `init` (offline framework
+        // assemble by symlink; openspec init is the only remaining network step) —
+        // NO `npx specrails-core` round-trip. When NO bundled core is present we fall
+        // through to the legacy npx probe + spawn, byte-identical to today.
+        const useBundledCore = (0, bundled_core_1.getBundledCoreCli)() !== null;
+        if (useBundledCore) {
+            // Materialize the framework for the selected provider (idempotent). The
+            // subsequent bundled `init` finds it already present (ensureFramework
+            // skips) and just assembles the workspace by symlink. Best-effort: a
+            // materialize failure is surfaced but the bundled init also re-runs
+            // ensureFramework, so it self-heals.
+            const provider = this._projectProviders.get(projectId) ?? 'claude';
+            try {
+                const fm = new framework_manager_1.FrameworkManager({
+                    broadcast: (msg) => this._broadcast(msg),
+                });
+                const mat = fm.materialize((0, bundled_core_1.getBundledCoreVersion)() ?? undefined, [provider]);
+                if (mat.ran && mat.errors.length > 0) {
+                    console.warn(`[SetupManager] framework materialize had errors: ${mat.errors.map((e) => `${e.provider}: ${e.message}`).join('; ')}`);
+                }
+            }
+            catch (err) {
+                console.warn(`[SetupManager] framework materialize threw (non-fatal): ${err.message}`);
+            }
         }
-        console.log(`[SetupManager] core runtime probe: ${probe.bin} -> ${probe.version}`);
-        const probeCmp = compareSemver(probe.version, MIN_NODE_NATIVE_CORE_VERSION);
-        if (probeCmp !== null && probeCmp < 0) {
-            this._broadcast({
-                type: 'setup_error',
-                projectId,
-                error: `Resolved specrails-core@${probe.version} is legacy; expected Node-native >= ${MIN_NODE_NATIVE_CORE_VERSION}.`,
-            });
-            return;
+        else {
+            // Legacy path: probe the npx-resolved core runtime (network) before spawn.
+            const probe = probeCoreRuntimeVersion(projectPath);
+            if (!probe.ok) {
+                this._broadcast({
+                    type: 'setup_error',
+                    projectId,
+                    error: `Failed to verify specrails-core runtime before install: ${probe.error ?? 'unknown error'}`,
+                });
+                return;
+            }
+            console.log(`[SetupManager] core runtime probe: ${probe.bin} -> ${probe.version}`);
+            const probeCmp = compareSemver(probe.version, MIN_NODE_NATIVE_CORE_VERSION);
+            if (probeCmp !== null && probeCmp < 0) {
+                this._broadcast({
+                    type: 'setup_error',
+                    projectId,
+                    error: `Resolved specrails-core@${probe.version} is legacy; expected Node-native >= ${MIN_NODE_NATIVE_CORE_VERSION}.`,
+                });
+                return;
+            }
         }
         let spawnConfigPath = null;
         if (hasConfig) {
@@ -659,7 +752,10 @@ class SetupManager {
         const initArgs = hasConfig
             ? ['--yes', '--from-config', spawnConfigPath ?? configPath]
             : ['--yes', '--root-dir', projectPath];
-        const child = spawnCoreInit(initArgs, projectPath);
+        // Bundled core (offline, node <cli> init) when available, else legacy npx.
+        const child = useBundledCore
+            ? spawnBundledCoreInit(initArgs, projectPath)
+            : spawnCoreInit(initArgs, projectPath);
         this._installProcesses.set(projectId, child);
         this._installLogBuffer.set(projectId, []);
         // spawnCoreInit uses shell:false on POSIX, so a spawn failure emits 'error'
@@ -738,7 +834,7 @@ class SetupManager {
                 this._broadcast({
                     type: 'setup_error',
                     projectId,
-                    error: formatBufferedInstallError(`npx specrails-core exited with code ${code ?? 'unknown'}`, logBuffer),
+                    error: formatBufferedInstallError(`${useBundledCore ? 'bundled specrails-core' : 'npx specrails-core'} exited with code ${code ?? 'unknown'}`, logBuffer),
                 });
             }
         });
@@ -769,7 +865,12 @@ class SetupManager {
         catch (err) {
             console.warn(`[SetupManager] Failed to pre-create enrich directories: ${err}`);
         }
-        const configPath = (0, path_1.join)(projectPath, '.specrails', 'install-config.yaml');
+        // Relocate-artifacts: the install config lives in the per-project HOME dir.
+        // The slug was allocated at addProject and mirrored into the shared registry
+        // before/at install time, so resolve it from there (legacy full-flow path —
+        // not exercised by the app's quick flow).
+        const enrichSlug = (0, artifact_registry_1.resolveArtifacts)(projectPath).entry?.slug;
+        const configPath = (0, install_config_path_1.installConfigPath)({ slug: enrichSlug, path: projectPath });
         const hasConfig = (0, fs_1.existsSync)(configPath);
         const enrichCmd = hasConfig ? '/specrails:enrich --from-config' : '/specrails:enrich';
         this._spawnSetupWithAdapter(projectId, projectPath, {
@@ -1148,16 +1249,17 @@ class SetupManager {
     getInstallTier(projectId) {
         return this._projectTiers.get(projectId);
     }
-    getSummary(projectPath) {
-        const config = readInstallConfig(projectPath);
+    getSummary(project) {
+        const config = readInstallConfig(project);
         const tier = config?.tier ?? 'quick';
         // Provider is authoritative from install-config.yaml when present; we
         // do NOT fall back to filesystem heuristics because both `.codex/` and
         // `.claude/` can legitimately coexist (e.g. a project that's been
         // re-init'd) and a generic `existsSync` probe would mis-route.
+        // Relocate-artifacts: the config lives in the per-project HOME dir.
         let provider = 'claude';
         try {
-            const text = (0, fs_1.readFileSync)((0, path_1.join)(projectPath, '.specrails', 'install-config.yaml'), 'utf-8');
+            const text = (0, fs_1.readFileSync)((0, install_config_path_1.installConfigPath)(project), 'utf-8');
             const m = text.match(/^provider:\s*(\w+)/m);
             if (m && m[1] && (0, providers_1.hasAdapter)(m[1]))
                 provider = m[1];
@@ -1165,7 +1267,7 @@ class SetupManager {
         catch {
             // Missing install-config — stay on claude default.
         }
-        return computeSummary(projectPath, tier, provider);
+        return computeSummary(project.path, tier, provider);
     }
 }
 exports.SetupManager = SetupManager;