specrails-desktop 2.7.0 → 2.9.0

package/server/dist/framework-manager.js

@@ -0,0 +1,248 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.atomicWrite = exports.FrameworkManager = void 0;
+exports.frameworkRoot = frameworkRoot;
+exports.readCurrentFrameworkVersion = readCurrentFrameworkVersion;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const bundled_core_1 = require("./bundled-core");
+const artifact_registry_1 = require("./artifact-registry");
+Object.defineProperty(exports, "atomicWrite", { enumerable: true, get: function () { return artifact_registry_1.atomicWrite; } });
+/** `~/.specrails/framework` — same home as the registry. */
+function frameworkRoot(home) {
+    return path_1.default.join((0, artifact_registry_1.resolveHome)(home), '.specrails', 'framework');
+}
+/** Path to the `current` symlink under the framework root. */
+function currentLink(home) {
+    return path_1.default.join(frameworkRoot(home), 'current');
+}
+/**
+ * The version `framework/current` resolves to, or null when `current` is absent
+ * / not a `<version>` dir. Reads the basename of the symlink target.
+ */
+function readCurrentFrameworkVersion(home) {
+    const link = currentLink(home);
+    try {
+        const st = fs_1.default.lstatSync(link);
+        let target;
+        if (st.isSymbolicLink()) {
+            target = fs_1.default.readlinkSync(link);
+        }
+        else if (st.isDirectory()) {
+            // Windows copy fallback: `current` is a real dir holding a marker.
+            target = link;
+        }
+        else {
+            return null;
+        }
+        const resolved = path_1.default.isAbsolute(target) ? target : path_1.default.resolve(frameworkRoot(home), target);
+        const base = path_1.default.basename(resolved);
+        return base === 'current' ? null : base;
+    }
+    catch {
+        return null;
+    }
+}
+class FrameworkManager {
+    home;
+    broadcast;
+    constructor(opts = {}) {
+        this.home = opts.home;
+        this.broadcast = opts.broadcast;
+    }
+    /** True when a usable bundled core is present (else all methods no-op). */
+    isAvailable() {
+        return (0, bundled_core_1.getBundledCoreCli)() !== null;
+    }
+    /** The bundled core version (the version the app should materialize), or null. */
+    bundledVersion() {
+        return (0, bundled_core_1.getBundledCoreVersion)();
+    }
+    /**
+     * Materialize the framework for `version` (default: the bundled core version)
+     * for each provider — idempotent + offline. Shells out to the bundled core
+     * `install-framework --no-swap` once per provider, so the materialize step
+     * NEVER moves `current`: the caller (`versionCheck`) materializes EVERY
+     * provider first, then issues a SINGLE `swapCurrent(version)` only when all of
+     * them succeeded. This prevents a half-installed multi-provider release from
+     * flipping `current` to a version whose other providerDirs are missing. No-ops
+     * (ran:false) when no bundled core is present.
+     */
+    materialize(version, providers = ['claude']) {
+        const cli = (0, bundled_core_1.getBundledCoreCli)();
+        if (!cli) {
+            return { ran: false, version: null, providers: [], errors: [] };
+        }
+        const ver = version ?? this.bundledVersion();
+        if (!ver) {
+            return { ran: false, version: null, providers: [], errors: [] };
+        }
+        const fwDir = frameworkRoot(this.home);
+        fs_1.default.mkdirSync(fwDir, { recursive: true });
+        const errors = [];
+        const done = [];
+        for (const provider of dedupe(providers)) {
+            const res = (0, child_process_1.spawnSync)(process.execPath, [
+                cli,
+                'install-framework',
+                '--framework-dir',
+                fwDir,
+                '--provider',
+                provider,
+                '--version',
+                ver,
+                // Materialize-all-then-swap-once: each provider is installed WITHOUT
+                // moving `current`; the finalising swap happens in versionCheck.
+                '--no-swap',
+            ], { env: this.childEnv(), encoding: 'utf-8', timeout: 120_000 });
+            if (res.error || (res.status ?? 1) !== 0) {
+                const msg = res.error?.message ?? (res.stderr || `exit ${res.status ?? 'unknown'}`);
+                errors.push({ provider, message: `${msg}`.trim() });
+            }
+            else {
+                done.push(provider);
+            }
+        }
+        return { ran: true, version: ver, providers: done, errors };
+    }
+    /**
+     * Atomically point `framework/current` at `version` via core's dedicated
+     * `swap-current` subcommand — the ONE finalising step after every provider was
+     * materialized with `--no-swap`. Guard/no-op when `current` already points at
+     * `version`. Returns true when `current` ended up at `version`.
+     *
+     * The `provider` param is retained for signature compatibility but is unused:
+     * `swap-current` only moves the version pointer (provider-invariant).
+     */
+    swapCurrent(version, _provider = 'claude') {
+        const cli = (0, bundled_core_1.getBundledCoreCli)();
+        if (!cli)
+            return false;
+        if (readCurrentFrameworkVersion(this.home) === version)
+            return true;
+        const fwDir = frameworkRoot(this.home);
+        const res = (0, child_process_1.spawnSync)(process.execPath, [cli, 'swap-current', '--framework-dir', fwDir, '--version', version], { env: this.childEnv(), encoding: 'utf-8', timeout: 120_000 });
+        if (res.error || (res.status ?? 1) !== 0)
+            return false;
+        return readCurrentFrameworkVersion(this.home) === version;
+    }
+    /**
+     * Compare the bundled core version with `framework/current`. When they differ
+     * (or current is absent), materialize the bundled version + swap `current` and
+     * broadcast `framework.updated`. Called on first-run + post-update. No-ops when
+     * no bundled core is present. Returns the resulting current version (or null).
+     */
+    versionCheck(providers = ['claude']) {
+        const bundled = this.bundledVersion();
+        if (!(0, bundled_core_1.getBundledCoreCli)() || !bundled) {
+            return { swapped: false, version: readCurrentFrameworkVersion(this.home) };
+        }
+        const current = readCurrentFrameworkVersion(this.home);
+        if (current === bundled) {
+            return { swapped: false, version: current };
+        }
+        // Materialize EVERY requested provider first (each with `--no-swap`), then
+        // swap `current` ONCE — and ONLY when every provider materialized cleanly.
+        // A partial multi-provider install must NEVER flip `current`: doing so would
+        // point `current` at a version whose other providerDirs are missing, so a
+        // rail spawning under a non-materialized provider would fail to assemble.
+        const mat = this.materialize(bundled, providers);
+        if (!mat.ran) {
+            return { swapped: false, version: current };
+        }
+        if (mat.errors.length > 0) {
+            // Do NOT swap; surface the failure (don't discard it, don't report success).
+            try {
+                this.broadcast?.({
+                    type: 'framework.update_failed',
+                    version: bundled,
+                    errors: mat.errors,
+                });
+            }
+            catch {
+                /* broadcast is best-effort */
+            }
+            return { swapped: false, version: current };
+        }
+        if (mat.providers.length === 0) {
+            // No errors yet nothing materialized (empty/duplicate-only provider list).
+            return { swapped: false, version: current };
+        }
+        const ok = this.swapCurrent(bundled);
+        if (ok) {
+            try {
+                this.broadcast?.({ type: 'framework.updated', version: bundled });
+            }
+            catch {
+                /* broadcast is best-effort */
+            }
+            return { swapped: true, version: bundled };
+        }
+        // Materialized cleanly but the swap itself failed — surface as a failure.
+        try {
+            this.broadcast?.({
+                type: 'framework.update_failed',
+                version: bundled,
+                errors: [{ provider: providers[0] ?? 'claude', message: 'swap-current failed' }],
+            });
+        }
+        catch {
+            /* broadcast is best-effort */
+        }
+        return { swapped: false, version: readCurrentFrameworkVersion(this.home) };
+    }
+    /**
+     * Assemble a project workspace by SYMLINKING the materialized framework into
+     * it (offline) via the bundled core `assemble` subcommand. Returns false (no-op)
+     * when no bundled core is present — caller falls back to legacy npx assembly.
+     */
+    assembleWorkspace(input) {
+        const cli = (0, bundled_core_1.getBundledCoreCli)();
+        if (!cli)
+            return { ran: false };
+        const ver = input.version ?? this.bundledVersion();
+        if (!ver)
+            return { ran: false };
+        const fwDir = frameworkRoot(this.home);
+        const res = (0, child_process_1.spawnSync)(process.execPath, [
+            cli,
+            'assemble',
+            '--workspace',
+            input.workspace,
+            '--framework-dir',
+            fwDir,
+            '--provider',
+            input.provider,
+            '--version',
+            ver,
+            '--code-root',
+            input.codeRoot,
+        ], { env: this.childEnv(), encoding: 'utf-8', timeout: 120_000 });
+        if (res.error || (res.status ?? 1) !== 0) {
+            const msg = res.error?.message ?? (res.stderr || `exit ${res.status ?? 'unknown'}`);
+            return { ran: true, error: `${msg}`.trim() };
+        }
+        return { ran: true };
+    }
+    /** Child env: thread the registry home so the core CLI co-locates framework + registry. */
+    childEnv() {
+        const env = { ...process.env };
+        if (this.home) {
+            env.SPECRAILS_REGISTRY_HOME = this.home;
+        }
+        // Point the bundled core CLI's scriptDir at the bundled package so its
+        // template/command sources resolve from the bundle, not a global install.
+        const coreRoot = process.env.SPECRAILS_BUNDLED_CORE_PATH;
+        if (coreRoot)
+            env.SPECRAILS_CORE_SCRIPT_DIR = coreRoot;
+        return env;
+    }
+}
+exports.FrameworkManager = FrameworkManager;
+function dedupe(values) {
+    return Array.from(new Set(values));
+}

package/server/dist/framework-migration.js

@@ -0,0 +1,308 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.providerDirFor = providerDirFor;
+exports.migrateWorkspaceToSymlinks = migrateWorkspaceToSymlinks;
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const framework_manager_1 = require("./framework-manager");
+const workspace_manager_1 = require("./workspace-manager");
+const artifact_registry_1 = require("./artifact-registry");
+/** The shared, statically-linked subtrees of a providerDir. `agent-memory` is
+ *  intentionally absent — it is real per-workspace state, never compared/linked. */
+const SHARED_SUBTREES = ['commands', 'agents', 'skills', 'rules'];
+/** Map a provider id to its providerDir name (mirrors core). */
+function providerDirFor(provider) {
+    if (provider === 'codex')
+        return '.codex';
+    if (provider === 'gemini')
+        return '.gemini';
+    return '.claude';
+}
+/** sha256 of a file's bytes, or null when unreadable. */
+function hashFile(p) {
+    try {
+        return crypto_1.default.createHash('sha256').update(fs_1.default.readFileSync(p)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `p` is a symbolic link. */
+function isSymlink(p) {
+    try {
+        return fs_1.default.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `p` is a real (non-symlink) directory. */
+function isRealDir(p) {
+    try {
+        const st = fs_1.default.lstatSync(p);
+        return st.isDirectory() && !st.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** Recursively list relative file paths under `dir` (dirs flattened to files). */
+function listFilesRel(dir, base = dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const abs = path_1.default.join(dir, e.name);
+        if (e.isSymbolicLink())
+            continue; // a symlink inside a copy is not a real file to compare
+        if (e.isDirectory()) {
+            out.push(...listFilesRel(abs, base));
+        }
+        else if (e.isFile()) {
+            out.push(path_1.default.relative(base, abs));
+        }
+    }
+    return out;
+}
+/** A file is a user/plugin custom agent (expected, never part of the framework). */
+function isCustomAgent(rel) {
+    return path_1.default.basename(rel).startsWith('custom-');
+}
+/**
+ * Compare the workspace providerDir's shared subtrees against
+ * `framework/current/<providerDir>/...`. A file present in the copy that differs
+ * from (or is missing in) `current` — excluding `custom-*` agents — counts as
+ * local divergence.
+ */
+function compareSharedSubtrees(workspaceProviderDir, fwProviderDir) {
+    let hadSharedSubtree = false;
+    for (const sub of SHARED_SUBTREES) {
+        const copyDir = path_1.default.join(workspaceProviderDir, sub);
+        if (!isRealDir(copyDir))
+            continue;
+        hadSharedSubtree = true;
+        const fwSub = path_1.default.join(fwProviderDir, sub);
+        for (const rel of listFilesRel(copyDir)) {
+            if (sub === 'agents' && isCustomAgent(rel))
+                continue; // expected, ignore
+            const copyHash = hashFile(path_1.default.join(copyDir, rel));
+            const fwHash = hashFile(path_1.default.join(fwSub, rel));
+            if (copyHash === null || fwHash === null || copyHash !== fwHash) {
+                return { matches: false, diverged: path_1.default.join(sub, rel), hadSharedSubtree };
+            }
+        }
+    }
+    return { matches: hadSharedSubtree, hadSharedSubtree };
+}
+/** Resolve a symlink target absolutely (or null). */
+function readlinkAbs(p) {
+    try {
+        const t = fs_1.default.readlinkSync(p);
+        return path_1.default.isAbsolute(t) ? t : path_1.default.resolve(path_1.default.dirname(p), t);
+    }
+    catch {
+        return null;
+    }
+}
+/** True when `linkPath` resolves into `<frameworkCurrent>/...`. */
+function linkResolvesIntoFramework(linkPath, fwCurrent) {
+    if (!isSymlink(linkPath))
+        return false;
+    const target = readlinkAbs(linkPath);
+    if (!target)
+        return false;
+    const norm = path_1.default.resolve(target);
+    const base = path_1.default.resolve(fwCurrent) + path_1.default.sep;
+    return norm === path_1.default.resolve(fwCurrent) || norm.startsWith(base);
+}
+const BAK_SUFFIX = '.pre-symlink.bak';
+/**
+ * Convert a workspace's per-workspace framework COPY into symlinks to
+ * `framework/current`. See the module docstring for the full safety contract.
+ *
+ * Runs the whole detect → backup → re-link → verify → cleanup/revert sequence
+ * under the registry file-lock so it never races a concurrent framework swap.
+ */
+function migrateWorkspaceToSymlinks(slug, projectPath, provider, opts = {}) {
+    const fm = opts.framework ?? new framework_manager_1.FrameworkManager({ home: opts.home });
+    const fwCurrent = path_1.default.join((0, framework_manager_1.frameworkRoot)(opts.home), 'current');
+    // Existence-gate: with no bundled core OR no materialized `current`, no-op.
+    if (!fm.isAvailable() || !fs_1.default.existsSync(fwCurrent)) {
+        return { outcome: 'no-bundle' };
+    }
+    return (0, artifact_registry_1.withFileLock)(opts.home, () => runMigration(slug, projectPath, provider, fwCurrent, fm, opts));
+}
+function emit(broadcast, type, extra) {
+    try {
+        broadcast?.({ type, ...extra });
+    }
+    catch {
+        /* observability is best-effort */
+    }
+}
+function runMigration(slug, projectPath, provider, fwCurrent, fm, opts) {
+    const providerDir = providerDirFor(provider);
+    const ws = (0, workspace_manager_1.workspacePathFor)(slug, opts.home);
+    const wsProviderDir = path_1.default.join(ws, providerDir);
+    const fwProviderDir = path_1.default.join(fwCurrent, providerDir);
+    // Idempotent: if any shared subtree is already a symlink into `current`, the
+    // workspace is migrated — no-op.
+    for (const sub of SHARED_SUBTREES) {
+        if (linkResolvesIntoFramework(path_1.default.join(wsProviderDir, sub), fwCurrent)) {
+            return { outcome: 'already-symlinked' };
+        }
+    }
+    // Detect the migratable real-copy layout + the local-divergence guard.
+    const cmp = compareSharedSubtrees(wsProviderDir, fwProviderDir);
+    if (!cmp.hadSharedSubtree) {
+        return { outcome: 'not-a-copy' };
+    }
+    if (!cmp.matches) {
+        emit(opts.broadcast, 'framework.migration_skipped', { slug, provider, reason: 'local-divergence', path: cmp.diverged });
+        return { outcome: 'skipped-divergence', detail: cmp.diverged };
+    }
+    // ── Backup the copied shared subtrees (never delete). ──────────────────────
+    const backedUp = [];
+    for (const sub of SHARED_SUBTREES) {
+        const live = path_1.default.join(wsProviderDir, sub);
+        if (!isRealDir(live))
+            continue;
+        const bak = live + BAK_SUFFIX;
+        try {
+            // Clear a stale backup from a prior aborted run.
+            if (fs_1.default.existsSync(bak))
+                fs_1.default.rmSync(bak, { recursive: true, force: true });
+            fs_1.default.renameSync(live, bak);
+            backedUp.push({ live, bak });
+        }
+        catch (err) {
+            // Could not back up — revert anything already moved and bail (no mutation).
+            restoreBackups(backedUp);
+            emit(opts.broadcast, 'framework.migration_skipped', { slug, provider, reason: 'backup-failed', path: sub, error: err.message });
+            return { outcome: 'skipped-divergence', detail: `backup-failed:${sub}` };
+        }
+    }
+    // ── Re-link via core's offline assemble (re-creates symlinks + agent-memory). ─
+    let assembled = false;
+    try {
+        const res = (0, workspace_manager_1.assembleWorkspaceFramework)(slug, projectPath, provider, {
+            home: opts.home,
+            framework: fm,
+            _skipMigrate: true,
+        });
+        assembled = res.assembled && !res.error;
+    }
+    catch {
+        assembled = false;
+    }
+    // ── Preserve agent-memory: if a real agent-memory survived only in a backup,
+    // move it into the live layout (assemble seeds an empty one; the user's
+    // existing memory must win). ────────────────────────────────────────────────
+    preserveAgentMemory(wsProviderDir, backedUp);
+    // ── Verify the new symlinks resolve INTO framework/current. ────────────────
+    const verified = assembled &&
+        SHARED_SUBTREES.some((sub) => linkResolvesIntoFramework(path_1.default.join(wsProviderDir, sub), fwCurrent));
+    if (!verified) {
+        // REVERT: remove any freshly-created (broken) symlinks/dirs, restore backups.
+        for (const { live } of backedUp) {
+            try {
+                if (fs_1.default.existsSync(live) || isSymlink(live))
+                    fs_1.default.rmSync(live, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        restoreBackups(backedUp);
+        emit(opts.broadcast, 'framework.migration_skipped', { slug, provider, reason: 'verify-failed' });
+        return { outcome: 'reverted', detail: 'verify-failed', backedUp: backedUp.map((b) => b.live) };
+    }
+    // ── Success cleanup. The shared framework files in each backup were proven
+    // byte-identical to `current` by the divergence guard, so deleting them loses
+    // nothing. EXCEPTION: a backup may also carry `custom-*` agent files (user /
+    // plugin agents that are NOT part of the framework and were ignored by the
+    // guard). The live `agents` is now a symlink into the read-only framework, so
+    // those custom files have no home there — we must NOT delete them. We retain
+    // any backup that holds custom-* content under `<sub>.custom.preserved/` and
+    // surface a `framework.custom_agents_preserved` event for observability;
+    // backups with only shared framework files are deleted. ──────────────────────
+    const preservedCustom = [];
+    for (const { live, bak } of backedUp) {
+        const customs = listFilesRel(bak).filter(isCustomAgent);
+        if (customs.length > 0) {
+            const preserved = live + '.custom.preserved';
+            try {
+                if (fs_1.default.existsSync(preserved))
+                    fs_1.default.rmSync(preserved, { recursive: true, force: true });
+                fs_1.default.renameSync(bak, preserved);
+                preservedCustom.push(...customs.map((c) => path_1.default.basename(c)));
+            }
+            catch {
+                /* keep the .bak as-is if we cannot rename — still non-destructive */
+            }
+        }
+        else {
+            try {
+                fs_1.default.rmSync(bak, { recursive: true, force: true });
+            }
+            catch {
+                /* leaving a stale .bak is harmless; never fail the migration on cleanup */
+            }
+        }
+    }
+    if (preservedCustom.length > 0) {
+        emit(opts.broadcast, 'framework.custom_agents_preserved', { slug, provider, files: preservedCustom });
+    }
+    emit(opts.broadcast, 'framework.migrated', { slug, provider, version: fm.bundledVersion() });
+    return { outcome: 'migrated', backedUp: backedUp.map((b) => b.live) };
+}
+/** Restore each `<sub>.pre-symlink.bak` back to its live path (revert). */
+function restoreBackups(backedUp) {
+    for (const { live, bak } of backedUp) {
+        try {
+            if (!fs_1.default.existsSync(bak))
+                continue;
+            if (fs_1.default.existsSync(live) || isSymlink(live))
+                fs_1.default.rmSync(live, { recursive: true, force: true });
+            fs_1.default.renameSync(bak, live);
+        }
+        catch {
+            /* best-effort revert — a surviving .bak is recoverable by hand */
+        }
+    }
+}
+/**
+ * Ensure the live `agent-memory/` holds the user's existing memory. If the
+ * post-assemble layout has an empty/absent agent-memory but a backup carried a
+ * populated one, move the backup's agent-memory into the live layout. Never
+ * overwrites a non-empty live agent-memory.
+ */
+function preserveAgentMemory(wsProviderDir, backedUp) {
+    const liveMem = path_1.default.join(wsProviderDir, 'agent-memory');
+    // agent-memory was NOT one of the backed-up shared subtrees (it's not in
+    // SHARED_SUBTREES), so a copy-layout's agent-memory still sits at the live
+    // path untouched. Nothing to move in the common case. This guard only handles
+    // a future layout where agent-memory lived under a backed-up subtree.
+    for (const { bak } of backedUp) {
+        const bakMem = path_1.default.join(bak, 'agent-memory');
+        if (!isRealDir(bakMem))
+            continue;
+        try {
+            if (!fs_1.default.existsSync(liveMem)) {
+                fs_1.default.renameSync(bakMem, liveMem);
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}

package/server/dist/index.js

@@ -25,6 +25,8 @@ const feature_flags_1 = require("./feature-flags");
 const mobile_1 = require("./mobile");
 const telemetry_receiver_1 = require("./telemetry-receiver");
 const telemetry_compactor_1 = require("./telemetry-compactor");
+const framework_manager_1 = require("./framework-manager");
+const artifact_registry_1 = require("./artifact-registry");
 const path_resolver_1 = require("./path-resolver");
 // Side-effect import: registers every bundled ProviderAdapter (claude, codex,
 // future providers) so `getAdapter`/`hasAdapter`/`listAdapters` are populated
@@ -418,6 +420,34 @@ function applyWsRateLimiting(ws) {
     registry.loadAll();
     _registry = registry;
     _getProjectCount = () => registry.listContexts().length;
+    // ─── Bundled framework update channel (Phase 6) ─────────────────────────────
+    // After the registry + projects have loaded, run a single framework
+    // version-check. On FIRST run it materializes the bundled framework to
+    // `~/.specrails/framework/<version>/` + points `current`; POST-UPDATE (a new
+    // app version ships a newer bundled core) it materializes the new version
+    // side-by-side and atomically swaps `current` → every workspace that links
+    // `current/...` jumps to it with no per-workspace work. The whole
+    // materialize+swap runs under the SAME registry file-lock that serialises
+    // artifact resolution, so a concurrently-spawning rail never observes a
+    // half-swapped `current` (a rail that already resolved `current` keeps its
+    // resolved framework — the atomic swap doesn't disturb open handles). No-op
+    // (graceful) when no bundled core is present — every project falls back to
+    // the legacy npx path. The `framework.updated` WS event is app-level (no
+    // projectId); the client WS layer ignores unknown message types.
+    try {
+        const framework = new framework_manager_1.FrameworkManager({
+            // `framework.updated` is app-level (no projectId) and not a member of the
+            // WsMessage union; cast at this single boundary.
+            broadcast: (msg) => broadcast(msg),
+        });
+        if (framework.isAvailable()) {
+            const providers = registry.installedProvidersUnion();
+            (0, artifact_registry_1.withFileLock)(undefined, () => framework.versionCheck(providers));
+        }
+    }
+    catch (err) {
+        console.error('[framework-manager] startup versionCheck failed (non-fatal):', err);
+    }
     // OTLP/JSON receiver — INTENTIONALLY UNAUTHENTICATED (H-01/H-02). The spawned
     // claude/codex CLIs post telemetry here with no auth header (queue-manager sets
     // OTEL_EXPORTER_OTLP_ENDPOINT but no OTEL_EXPORTER_OTLP_HEADERS), so it cannot

package/server/dist/install-config-path.js

@@ -0,0 +1,73 @@
+"use strict";
+// install-config-path — the SINGLE resolver for `install-config.yaml`.
+//
+// PRIMARY relocation fix: the install config is core's INPUT at project-creation
+// time (the desktop-written YAML that core reads via `--from-config`). It used to
+// be written into `<project.path>/.specrails/install-config.yaml`, which created
+// a `.specrails/` directory inside the user's repo BEFORE relocation could flip
+// on — the very leak the relocate-artifacts feature exists to prevent.
+//
+// It now lives in the per-project app-managed HOME dir
+// `$HOME/.specrails/projects/<slug>/install-config.yaml`. That directory:
+//   - always exists / can always be created (independent of whether the
+//     workspace subdir has been populated by core yet), and
+//   - is NEVER inside the user's repo, so a fresh setup creates ZERO `.specrails`
+//     in the repo.
+//
+// This is deliberately NOT the workspace (`resolveProjectExecution`): the config
+// is read at INSTALL time, before core populates the workspace and before the
+// relocation gate flips. The HOME per-project dir is the one location guaranteed
+// to be available across both the relocated and the non-bundled flows.
+//
+// The slug is allocated by `addProject` (desktop.sqlite) BEFORE any setup runs,
+// so every install-config reader/writer has it. When a slug is somehow absent
+// (defensive — e.g. a synthetic call path), we fall back to a deterministic tmp
+// STAGING path keyed off the repo path — never the repo itself.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectHomeDir = projectHomeDir;
+exports.installConfigPath = installConfigPath;
+exports.ensureInstallConfigDir = ensureInstallConfigDir;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+/** `$HOME` override (mirrors `resolveHome` in artifact-registry / tests). */
+function resolveHome(home) {
+    return home ?? process.env.SPECRAILS_REGISTRY_HOME ?? os_1.default.homedir();
+}
+/** True when a slug is a safe single path segment (no separators / traversal). */
+function isSafeSlug(slug) {
+    return (typeof slug === 'string' &&
+        slug.trim().length > 0 &&
+        !slug.includes('/') &&
+        !slug.includes('\\') &&
+        !slug.includes('..'));
+}
+/** The per-project app-managed HOME dir: `$HOME/.specrails/projects/<slug>`. */
+function projectHomeDir(slug, home) {
+    return path_1.default.join(resolveHome(home), '.specrails', 'projects', slug);
+}
+/**
+ * Resolve the install-config.yaml path for a project — the per-project HOME dir
+ * when the slug is available (the normal case), else a deterministic tmp-staging
+ * path keyed off the repo path. NEVER returns a path inside the user's repo.
+ */
+function installConfigPath(project, home) {
+    if (isSafeSlug(project.slug)) {
+        return path_1.default.join(projectHomeDir(project.slug, home), 'install-config.yaml');
+    }
+    // Defensive fallback: a stable tmp staging dir (NOT the repo) so a slug-less
+    // call still never leaks into the user's tree. The hash keeps it per-repo; the
+    // file keeps the canonical `install-config.yaml` basename.
+    const hash = (0, crypto_1.createHash)('sha256').update(path_1.default.resolve(project.path)).digest('hex').slice(0, 16);
+    return path_1.default.join(os_1.default.tmpdir(), `specrails-desktop-install-config-${hash}`, 'install-config.yaml');
+}
+/** Ensure the parent directory of the install-config exists (idempotent). */
+function ensureInstallConfigDir(project, home) {
+    const file = installConfigPath(project, home);
+    fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
+    return file;
+}