specrails-desktop 2.36.0 → 2.42.2

package/server/dist/desktop-db.js

@@ -3,14 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_SEARCH_INDEX_DDL = void 0;
 exports.setProjectProvidersMirror = setProjectProvidersMirror;
 exports.getDesktopDbPath = getDesktopDbPath;
+exports.rebuildAgentSearchIndex = rebuildAgentSearchIndex;
 exports.initDesktopDb = initDesktopDb;
 exports.listProjects = listProjects;
 exports.getProject = getProject;
 exports.getProjectBySlug = getProjectBySlug;
 exports.getProjectByPath = getProjectByPath;
 exports.addProject = addProject;
+exports.listProjectRepositories = listProjectRepositories;
+exports.addProjectRepository = addProjectRepository;
+exports.updateProjectRepository = updateProjectRepository;
+exports.removeProjectRepository = removeProjectRepository;
 exports.removeProject = removeProject;
 exports.touchProject = touchProject;
 exports.getDesktopSetting = getDesktopSetting;
@@ -38,6 +44,9 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const secure_fs_1 = require("./util/secure-fs");
+const sqlite_migrations_1 = require("./util/sqlite-migrations");
+const crypto_1 = require("crypto");
+const project_repositories_1 = require("./project-repositories");
 function parseProviders(raw, primary) {
     if (raw) {
         try {
@@ -63,9 +72,11 @@ function setProjectProvidersMirror(fn) {
     _detectedMirrorSupplier = fn;
 }
 const PRIMARY_PREFERENCE = ['claude', 'codex', 'gemini', 'kimi'];
-function mapProjectRow(raw) {
+function mapProjectRow(db, raw) {
     if (!raw)
         return undefined;
+    const repositories = listProjectRepositories(db, raw.id);
+    const membership = { repositories, primaryRepositoryId: repositories.find((repository) => repository.isPrimary)?.id };
     const provider = (raw.provider ?? 'claude');
     const stored = parseProviders(raw.providers, provider);
     const detected = _detectedMirrorSupplier?.();
@@ -74,9 +85,9 @@ function mapProjectRow(raw) {
         let primary = mirrored.includes(provider) ? provider : undefined;
         if (!primary)
             primary = PRIMARY_PREFERENCE.find((p) => mirrored.includes(p)) ?? mirrored[0];
-        return { ...raw, provider: primary, providers: [...mirrored] };
+        return { ...raw, ...membership, provider: primary, providers: [...mirrored] };
     }
-    return { ...raw, provider, providers: stored };
+    return { ...raw, ...membership, provider, providers: stored };
 }
 // ─── Desktop DB path ──────────────────────────────────────────────────────────
 function getDesktopDbPath() {
@@ -102,9 +113,8 @@ function migrateLegacyDbFile(dbPath) {
             // is renamed first, a crash in the (sub-ms) window between renames leaves
             // `desktop.sqlite` with no adjacent WAL -> un-checkpointed commits in the
             // orphaned `hub.sqlite-wal` are silently discarded on next open. Moving the
-            // sidecars first means an interrupted migration leaves the WAL/SHM still
-            // matched to the legacy main file (the new file does not exist yet, so the
-            // guard above re-runs the whole migration on the next launch).
+            // sidecars first keeps the new main file from being opened without its
+            // WAL. An interrupted migration resumes before opening either main file.
             for (const suffix of ['-wal', '-shm']) {
                 if (fs_1.default.existsSync(legacyPath + suffix)) {
                     fs_1.default.renameSync(legacyPath + suffix, dbPath + suffix);
@@ -114,12 +124,62 @@ function migrateLegacyDbFile(dbPath) {
         }
     }
     catch (err) {
-        console.warn('[desktop-db] could not migrate legacy hub.sqlite:', err);
+        // A failed rename must never fall through into creating an empty catalog.
+        // Tolerate only a second startup that already completed the same rename.
+        if (!fs_1.default.existsSync(legacyPath) && fs_1.default.existsSync(dbPath))
+            return;
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not migrate the existing project database from hub.sqlite to desktop.sqlite: ${detail}`, { cause: err });
     }
 }
 function getProjectDbPath(slug) {
     return path_1.default.join(os_1.default.homedir(), '.specrails', 'projects', slug, 'jobs.sqlite');
 }
+// ─── Mission search index ─────────────────────────────────────────────────────
+/**
+ * DDL for the mission full-text index (migration 24). Kept as a constant so
+ * `rebuildAgentSearchIndex` and tests can reason about the same schema. The
+ * column order matters: `content` is column 3, which is what `snippet()` and
+ * `highlight()` address in `agent-store.ts`.
+ */
+exports.AGENT_SEARCH_INDEX_DDL = `
+  CREATE VIRTUAL TABLE IF NOT EXISTS agent_messages_fts USING fts5(
+    conversation_id UNINDEXED,
+    message_id UNINDEXED,
+    role UNINDEXED,
+    content,
+    tokenize='trigram remove_diacritics 1'
+  );
+  CREATE TRIGGER IF NOT EXISTS agent_messages_fts_ai AFTER INSERT ON agent_messages BEGIN
+    INSERT INTO agent_messages_fts (conversation_id, message_id, role, content)
+    VALUES (new.conversation_id, new.id, new.role, new.content);
+  END;
+  CREATE TRIGGER IF NOT EXISTS agent_messages_fts_ad AFTER DELETE ON agent_messages BEGIN
+    DELETE FROM agent_messages_fts WHERE message_id = old.id;
+  END;
+  CREATE TRIGGER IF NOT EXISTS agent_messages_fts_au AFTER UPDATE OF content, role, conversation_id ON agent_messages BEGIN
+    DELETE FROM agent_messages_fts WHERE message_id = old.id;
+    INSERT INTO agent_messages_fts (conversation_id, message_id, role, content)
+    VALUES (new.conversation_id, new.id, new.role, new.content);
+  END;
+`;
+/**
+ * Re-derive the whole mission search index from `agent_messages`. Idempotent
+ * and cheap (the corpus is a few MB at most); the migration calls it once, and
+ * any future bulk writer that bypasses SQL triggers (an import, a repair tool)
+ * must call it afterwards. Runs in one transaction so a reader never observes
+ * a half-empty index.
+ */
+function rebuildAgentSearchIndex(db) {
+    const tx = db.transaction(() => {
+        db.exec('DELETE FROM agent_messages_fts');
+        db.exec(`
+      INSERT INTO agent_messages_fts (conversation_id, message_id, role, content)
+      SELECT conversation_id, id, role, content FROM agent_messages
+    `);
+    });
+    tx();
+}
 // ─── Schema migrations ────────────────────────────────────────────────────────
 // NOTE: existing migrations below intentionally keep the legacy `hub_settings`
 // table name — they are append-only history and must stay byte-identical for
@@ -133,8 +193,6 @@ function applyDesktopMigrations(db) {
       applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
     );
   `);
-    const appliedVersions = new Set(db.prepare('SELECT version FROM schema_migrations').all()
-        .map((r) => r.version));
     const migrations = [
         // Migration 1: projects and hub_settings tables
         () => {
@@ -484,23 +542,102 @@ function applyDesktopMigrations(db) {
         CREATE INDEX IF NOT EXISTS idx_blueprint_messages_conv ON blueprint_messages(conversation_id, created_at);
       `);
         },
+        // 23: durable Builder snapshots (harden-project-builder-snapshots). The
+        // blueprint used to live ONLY in client memory — the persisted assistant
+        // rows were stripped of the blueprint-draft JSON — so a closed panel, a
+        // refresh, or a silently rejected block lost everything the model had
+        // produced (and billed). Now every ACCEPTED snapshot is stored on the
+        // conversation (normalized + exact raw payload), the model's unstripped
+        // reply is kept per message for forensics/re-parsing, the last rejection
+        // is recorded so a manual repair can resume after a restart, and a commit
+        // links the conversation to the project it created (so the resume list
+        // only offers unfinished blueprints).
+        () => {
+            db.exec(`
+        ALTER TABLE blueprint_conversations ADD COLUMN blueprint_json TEXT;
+        ALTER TABLE blueprint_conversations ADD COLUMN raw_blueprint_json TEXT;
+        ALTER TABLE blueprint_conversations ADD COLUMN snapshot_updated_at TEXT;
+        ALTER TABLE blueprint_conversations ADD COLUMN snapshot_issue_json TEXT;
+        ALTER TABLE blueprint_conversations ADD COLUMN committed_project_id TEXT;
+        ALTER TABLE blueprint_messages ADD COLUMN raw_content TEXT;
+      `);
+        },
+        // 24: mission search (search-missions-in-palette). A standard FTS5 table
+        // (NOT external-content: `agent_messages` has a TEXT primary key, so its
+        // rowid is implicit and a VACUUM may renumber it — an external-content
+        // index keyed on that rowid would silently desync) carrying its own copy of
+        // every message body plus UNINDEXED conversation/message/role columns so a
+        // search never has to join back. The trigram tokenizer gives substring
+        // semantics ("etris" finds "Tetris") with an index and `snippet()`;
+        // `remove_diacritics 1` makes "mision" find "misión". Three triggers keep
+        // it in sync so every existing writer stays untouched; the one-off rebuild
+        // indexes the history already on disk.
+        () => {
+            db.exec(exports.AGENT_SEARCH_INDEX_DDL);
+            rebuildAgentSearchIndex(db);
+        },
+        // 25: Builder decision cards (premium-milestone-progress follow-up): a user
+        // turn sent from a one-click card ("surprise me", "approve") keeps its
+        // intent so the thread renders the settled decision card in place of the
+        // prompt bubble — across resumes and locale switches.
+        () => {
+            db.exec(`ALTER TABLE blueprint_messages ADD COLUMN intent TEXT;`);
+        },
+        // 26: logical projects retain their primary identity and one shared backlog.
+        () => {
+            db.exec(`
+        CREATE TABLE project_repositories (
+          id TEXT PRIMARY KEY,
+          project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+          name TEXT NOT NULL,
+          path TEXT NOT NULL,
+          canonical_key TEXT NOT NULL,
+          git_identity TEXT,
+          is_primary INTEGER NOT NULL DEFAULT 0 CHECK (is_primary IN (0, 1)),
+          kind TEXT NOT NULL CHECK (kind IN ('git', 'folder')),
+          integration_branch TEXT,
+          added_at TEXT NOT NULL DEFAULT (datetime('now')),
+          UNIQUE(project_id, canonical_key)
+        );
+        CREATE UNIQUE INDEX project_repositories_primary ON project_repositories(project_id) WHERE is_primary = 1;
+        CREATE UNIQUE INDEX project_repositories_git_identity ON project_repositories(project_id, git_identity) WHERE git_identity IS NOT NULL;
+      `);
+            const insert = db.prepare(`INSERT INTO project_repositories (id, project_id, name, path, canonical_key, is_primary, kind, added_at) VALUES (?, ?, ?, ?, ?, 1, ?, ?)`);
+            for (const project of db.prepare('SELECT id, name, path, added_at FROM projects').all()) {
+                insert.run(`primary-${project.id}`, project.id, project.name, project.path, (0, project_repositories_1.repositoryPathKey)((0, project_repositories_1.canonicalRepositoryPath)(project.path)), (0, project_repositories_1.legacyRepositoryKind)(project.path), project.added_at);
+            }
+        },
+        // 27: durable mission inputs. Pending corrections survive a process restart
+        // as visible interrupted user messages, without silently replaying actions.
+        () => {
+            db.exec(`
+        CREATE TABLE agent_inputs (
+          id TEXT PRIMARY KEY,
+          conversation_id TEXT NOT NULL REFERENCES agent_conversations(id) ON DELETE CASCADE,
+          queue_id TEXT NOT NULL,
+          text TEXT NOT NULL,
+          options_json TEXT NOT NULL DEFAULT '{}',
+          enqueue_payload TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'delivered', 'cancelled', 'interrupted')),
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          message_id TEXT REFERENCES agent_messages(id) ON DELETE SET NULL,
+          UNIQUE(conversation_id, queue_id)
+        );
+        CREATE INDEX idx_agent_inputs_pending ON agent_inputs(conversation_id, created_at) WHERE status = 'pending';
+        CREATE UNIQUE INDEX idx_agent_inputs_message ON agent_inputs(message_id) WHERE message_id IS NOT NULL;
+      `);
+        },
+        // 28: provider receipt is independent of transcript settlement. Existing
+        // delivered inputs were accepted, but have no evidence of being read.
+        () => {
+            db.exec(`
+        ALTER TABLE agent_inputs ADD COLUMN receipt TEXT NOT NULL DEFAULT 'sent'
+          CHECK (receipt IN ('sent', 'received', 'read'));
+        UPDATE agent_inputs SET receipt = 'received' WHERE status = 'delivered';
+      `);
+        },
     ];
-    for (let i = 0; i < migrations.length; i++) {
-        const version = i + 1;
-        if (!appliedVersions.has(version)) {
-            // Run each migration body and its version INSERT atomically (mirrors
-            // db.ts applyMigrations). SQLite DDL is transactional, so a crash/failure
-            // mid-migration rolls back the whole body instead of leaving a half-applied
-            // schema with the version unrecorded — which previously re-ran a bare
-            // `ALTER TABLE ADD COLUMN` on next startup and bricked app launch forever
-            // with 'duplicate column name'.
-            const tx = db.transaction(() => {
-                migrations[i]();
-                db.prepare('INSERT OR IGNORE INTO schema_migrations (version) VALUES (?)').run(version);
-            });
-            tx();
-        }
-    }
+    (0, sqlite_migrations_1.applyNumberedMigrations)(db, migrations);
 }
 // ─── Public API ───────────────────────────────────────────────────────────────
 function initDesktopDb(dbPath = getDesktopDbPath()) {
@@ -511,29 +648,35 @@ function initDesktopDb(dbPath = getDesktopDbPath()) {
     // Rebrand compat: pick up a pre-rename hub.sqlite before opening.
     migrateLegacyDbFile(dbPath);
     const db = new better_sqlite3_1.default(dbPath);
-    db.pragma('journal_mode = WAL');
-    db.pragma('foreign_keys = ON');
-    // Wait up to 5s on a lock instead of throwing SQLITE_BUSY, and cap the WAL.
-    db.pragma('busy_timeout = 5000');
-    db.pragma('journal_size_limit = 10000000'); // ~10 MB
-    applyDesktopMigrations(db);
-    // H-13: desktop.sqlite stores webhook HMAC secrets in plaintext — restrict it
-    // (and its WAL sidecars) to owner read/write.
-    if (dbPath !== ':memory:')
-        (0, secure_fs_1.secureDbFile)(dbPath);
+    try {
+        db.pragma('journal_mode = WAL');
+        db.pragma('foreign_keys = ON');
+        // Wait up to 5s on a lock instead of throwing SQLITE_BUSY, and cap the WAL.
+        db.pragma('busy_timeout = 5000');
+        db.pragma('journal_size_limit = 10000000'); // ~10 MB
+        applyDesktopMigrations(db);
+        // H-13: desktop.sqlite stores webhook HMAC secrets in plaintext — restrict it
+        // (and its WAL sidecars) to owner read/write.
+        if (dbPath !== ':memory:')
+            (0, secure_fs_1.secureDbFile)(dbPath);
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
     return db;
 }
 function listProjects(db) {
-    return db.prepare('SELECT * FROM projects ORDER BY added_at ASC').all().map((r) => mapProjectRow(r));
+    return db.prepare('SELECT * FROM projects ORDER BY added_at ASC').all().map((r) => mapProjectRow(db, r));
 }
 function getProject(db, id) {
-    return mapProjectRow(db.prepare('SELECT * FROM projects WHERE id = ?').get(id));
+    return mapProjectRow(db, db.prepare('SELECT * FROM projects WHERE id = ?').get(id));
 }
 function getProjectBySlug(db, slug) {
-    return mapProjectRow(db.prepare('SELECT * FROM projects WHERE slug = ?').get(slug));
+    return mapProjectRow(db, db.prepare('SELECT * FROM projects WHERE slug = ?').get(slug));
 }
 function getProjectByPath(db, projectPath) {
-    return mapProjectRow(db.prepare('SELECT * FROM projects WHERE path = ?').get(projectPath));
+    return mapProjectRow(db, db.prepare('SELECT * FROM projects WHERE path = ?').get(projectPath));
 }
 function addProject(db, project) {
     const dbPath = getProjectDbPath(project.slug);
@@ -542,12 +685,65 @@ function addProject(db, project) {
         : [project.provider ?? 'claude'];
     // Primary provider = explicit override, else the first selected provider.
     const provider = project.provider ?? providers[0];
-    db.prepare(`
-    INSERT INTO projects (id, slug, name, path, db_path, provider, providers)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-  `).run(project.id, project.slug, project.name, project.path, dbPath, provider, JSON.stringify(providers));
+    // Low-level callers may register unavailable legacy roots. HTTP validates all
+    // roots first; membership and project rows are still committed atomically here.
+    const roots = [(0, project_repositories_1.inspectRepositoryPath)({ path: project.path, name: project.name }, false), ...(project.repositories ?? []).map((input) => (0, project_repositories_1.inspectRepositoryPath)(input))];
+    (0, project_repositories_1.assertDistinctRepositories)(roots);
+    db.transaction(() => {
+        db.prepare(`
+      INSERT INTO projects (id, slug, name, path, db_path, provider, providers)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(project.id, project.slug, project.name, project.path, dbPath, provider, JSON.stringify(providers));
+        const insert = db.prepare(`INSERT INTO project_repositories (id, project_id, name, path, canonical_key, git_identity, is_primary, kind, integration_branch) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        roots.forEach((root, index) => insert.run(index === 0 ? `primary-${project.id}` : (0, crypto_1.randomUUID)(), project.id, root.name ?? path_1.default.basename(root.path), index === 0 ? project.path : root.path, root.canonicalKey, root.gitIdentity, index === 0 ? 1 : 0, root.kind, root.integrationBranch ?? null));
+    })();
     return getProject(db, project.id);
 }
+function listProjectRepositories(db, projectId) {
+    return db.prepare('SELECT * FROM project_repositories WHERE project_id = ? ORDER BY is_primary DESC, added_at, rowid').all(projectId).map((row) => ({
+        id: row.id, projectId: row.project_id, name: row.name, path: row.path,
+        isPrimary: row.is_primary === 1, kind: row.kind, integrationBranch: row.integration_branch,
+        addedAt: row.added_at, available: (0, project_repositories_1.repositoryAvailable)(row.path),
+    }));
+}
+function addProjectRepository(db, projectId, input) {
+    if (!getProject(db, projectId))
+        throw new project_repositories_1.RepositoryValidationError('Project not found', 'project_not_found', 404);
+    const root = (0, project_repositories_1.inspectRepositoryPath)(input);
+    const existing = listProjectRepositories(db, projectId).map((repo) => (0, project_repositories_1.inspectRepositoryPath)(repo, false));
+    (0, project_repositories_1.assertDistinctRepositories)([...existing, root]);
+    const id = (0, crypto_1.randomUUID)();
+    db.prepare(`INSERT INTO project_repositories (id, project_id, name, path, canonical_key, git_identity, kind, integration_branch) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(id, projectId, root.name ?? path_1.default.basename(root.path), root.path, root.canonicalKey, root.gitIdentity, root.kind, root.integrationBranch ?? null);
+    return listProjectRepositories(db, projectId).find((repo) => repo.id === id);
+}
+function updateProjectRepository(db, projectId, repositoryId, input) {
+    const repositories = listProjectRepositories(db, projectId);
+    const current = repositories.find((repo) => repo.id === repositoryId);
+    if (!current)
+        throw new project_repositories_1.RepositoryValidationError('Repository does not belong to this project', 'repository_not_found', 404);
+    if (current.isPrimary && input.path !== undefined)
+        throw new project_repositories_1.RepositoryValidationError('The primary project path cannot be relocated here', 'primary_repository_protected', 409);
+    const next = { ...current, ...input };
+    const root = (0, project_repositories_1.inspectRepositoryPath)(next, input.path !== undefined);
+    if (input.path === undefined && !(0, project_repositories_1.repositoryAvailable)(current.path)) {
+        root.kind = current.kind;
+        root.gitIdentity = db.prepare('SELECT git_identity FROM project_repositories WHERE id = ?').get(repositoryId).git_identity;
+    }
+    (0, project_repositories_1.assertDistinctRepositories)([...repositories.filter((repo) => repo.id !== repositoryId).map((repo) => (0, project_repositories_1.inspectRepositoryPath)(repo, false)), root]);
+    db.prepare('UPDATE project_repositories SET name = ?, path = ?, canonical_key = ?, git_identity = ?, kind = ?, integration_branch = ? WHERE project_id = ? AND id = ?')
+        .run(root.name ?? current.name, input.path === undefined ? current.path : root.path, root.canonicalKey, root.gitIdentity, root.kind, root.integrationBranch ?? null, projectId, repositoryId);
+    return listProjectRepositories(db, projectId).find((repo) => repo.id === repositoryId);
+}
+/** Removes the association only. Operational reference guards belong to ProjectRegistry. */
+function removeProjectRepository(db, projectId, repositoryId) {
+    const current = listProjectRepositories(db, projectId).find((repo) => repo.id === repositoryId);
+    if (!current)
+        throw new project_repositories_1.RepositoryValidationError('Repository does not belong to this project', 'repository_not_found', 404);
+    if (current.isPrimary)
+        throw new project_repositories_1.RepositoryValidationError('The primary repository cannot be removed', 'primary_repository_protected', 409);
+    db.prepare('DELETE FROM project_repositories WHERE project_id = ? AND id = ?').run(projectId, repositoryId);
+}
 function removeProject(db, id) {
     db.prepare('DELETE FROM projects WHERE id = ?').run(id);
     // No FK on agent_conversations.pinned_project_id — unpin so orphaned agent

package/server/dist/desktop-router.js

@@ -10,9 +10,11 @@ const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const net_1 = __importDefault(require("net"));
 const dns_1 = __importDefault(require("dns"));
+const project_repositories_1 = require("./project-repositories");
 const desktop_db_1 = require("./desktop-db");
 const webhook_manager_1 = require("./webhook-manager");
 const core_update_manager_1 = require("./core-update-manager");
+const framework_reseed_1 = require("./framework-reseed");
 const specrails_tech_client_1 = require("./specrails-tech-client");
 const core_compat_1 = require("./core-compat");
 const providers_1 = require("./providers");
@@ -453,7 +455,7 @@ function createDesktopRouter(registry, broadcast) {
     });
     // POST /api/projects — register a new project by path
     router.post('/projects', async (req, res) => {
-        const { path: projectPath, name, provider, providers: providersRaw } = req.body ?? {};
+        const { path: projectPath, name, provider, providers: providersRaw, repositories: repositoriesRaw } = req.body ?? {};
         if (!projectPath || typeof projectPath !== 'string') {
             res.status(400).json({ error: 'path is required' });
             return;
@@ -545,6 +547,23 @@ function createDesktopRouter(registry, broadcast) {
             return;
         }
         const canonicalPath = canonicalizePath(resolvedPath);
+        let repositories = [];
+        try {
+            if (repositoriesRaw !== undefined && !Array.isArray(repositoriesRaw))
+                throw new project_repositories_1.RepositoryValidationError('repositories must be an array');
+            repositories = (repositoriesRaw ?? []).map((input) => (0, project_repositories_1.inspectRepositoryPath)(input));
+            const primary = (0, project_repositories_1.inspectRepositoryPath)({ path: canonicalPath });
+            (0, project_repositories_1.assertDistinctRepositories)([primary, ...repositories.map((input) => (0, project_repositories_1.inspectRepositoryPath)(input))]);
+            if (repositories.some((repository) => !isPathSafe(repository.path)))
+                throw new project_repositories_1.RepositoryValidationError('Registering system directories is not allowed');
+        }
+        catch (err) {
+            if (err instanceof project_repositories_1.RepositoryValidationError) {
+                res.status(err.status).json({ error: err.message, code: err.code });
+                return;
+            }
+            throw err;
+        }
         // LOW-04: Reject registration of system-critical directories
         if (!isPathSafe(canonicalPath)) {
             res.status(400).json({ error: 'Registering system directories is not allowed' });
@@ -568,6 +587,7 @@ function createDesktopRouter(registry, broadcast) {
                 path: canonicalPath,
                 provider: providers[0],
                 providers,
+                repositories,
             });
             broadcast({
                 type: 'desktop.project_added',
@@ -593,7 +613,10 @@ function createDesktopRouter(registry, broadcast) {
         catch (err) {
             const message = err.message ?? '';
             // SQLite UNIQUE constraint violation means path or slug already registered
-            if (message.includes('UNIQUE')) {
+            if (err instanceof project_repositories_1.RepositoryValidationError) {
+                res.status(err.status).json({ error: err.message, code: err.code, details: err.details });
+            }
+            else if (message.includes('UNIQUE')) {
                 res.status(409).json({ error: 'A project with this path is already registered' });
             }
             else {
@@ -602,6 +625,68 @@ function createDesktopRouter(registry, broadcast) {
             }
         }
     });
+    // The logical project keeps one backlog; these routes only edit membership.
+    const sendRepositoryError = (err, res) => {
+        if (err instanceof project_repositories_1.RepositoryValidationError)
+            res.status(err.status).json({ error: err.message, code: err.code, details: err.details });
+        else {
+            console.error('[desktop] repository operation failed:', err);
+            res.status(500).json({ error: 'Could not update project repositories' });
+        }
+    };
+    const broadcastRepositories = () => broadcast({ type: 'desktop.projects', projects: (0, desktop_db_1.listProjects)(registry.desktopDb), timestamp: new Date().toISOString() });
+    router.get('/projects/:projectId/repositories', (req, res) => {
+        const project = (0, desktop_db_1.listProjects)(registry.desktopDb).find((item) => item.id === req.params.projectId);
+        if (!project) {
+            res.status(404).json({ error: 'Project not found' });
+            return;
+        }
+        res.json({ repositories: (0, project_repositories_1.getProjectRepositories)(project), primaryRepositoryId: project.primaryRepositoryId });
+    });
+    router.post('/projects/:projectId/repositories', (req, res) => {
+        try {
+            const input = (0, project_repositories_1.inspectRepositoryPath)(req.body);
+            if (!isPathSafe(input.path))
+                throw new project_repositories_1.RepositoryValidationError('Registering system directories is not allowed');
+            const repository = registry.addRepository(req.params.projectId, input);
+            broadcastRepositories();
+            res.status(201).json({ repository, project: registry.getProjectRow(req.params.projectId) });
+        }
+        catch (err) {
+            sendRepositoryError(err, res);
+        }
+    });
+    router.patch('/projects/:projectId/repositories/:repositoryId', (req, res) => {
+        try {
+            const body = req.body ?? {};
+            const input = {};
+            for (const key of ['path', 'name', 'integrationBranch'])
+                if (Object.prototype.hasOwnProperty.call(body, key))
+                    Object.assign(input, { [key]: body[key] });
+            if (input.path !== undefined) {
+                const inspected = (0, project_repositories_1.inspectRepositoryPath)(input);
+                if (!isPathSafe(inspected.path))
+                    throw new project_repositories_1.RepositoryValidationError('Registering system directories is not allowed');
+                input.path = inspected.path;
+            }
+            const repository = registry.updateRepository(req.params.projectId, req.params.repositoryId, input);
+            broadcastRepositories();
+            res.json({ repository, project: registry.getProjectRow(req.params.projectId) });
+        }
+        catch (err) {
+            sendRepositoryError(err, res);
+        }
+    });
+    router.delete('/projects/:projectId/repositories/:repositoryId', (req, res) => {
+        try {
+            registry.removeRepository(req.params.projectId, req.params.repositoryId);
+            broadcastRepositories();
+            res.json({ ok: true, project: registry.getProjectRow(req.params.projectId) });
+        }
+        catch (err) {
+            sendRepositoryError(err, res);
+        }
+    });
     // POST /api/projects/:id/assemble-retry — re-run the silent workspace
     // assemble for the providers that failed (or every detected provider when
     // nothing is recorded as failed). 202; progress rides project.assemble_progress.
@@ -679,14 +764,24 @@ function createDesktopRouter(registry, broadcast) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
-        const resolvedPath = canonicalizePath(path_1.default.resolve(queryPath));
-        const ctx = registry.getContextByPath(resolvedPath);
-        if (!ctx) {
-            res.status(404).json({ error: 'No project registered for this path' });
-            return;
+        try {
+            const projectId = typeof req.query.projectId === 'string' ? req.query.projectId : undefined;
+            const project = (0, project_repositories_1.resolveRepositoryProject)((0, desktop_db_1.listProjects)(registry.desktopDb), queryPath, projectId);
+            if (!project) {
+                res.status(404).json({ error: 'No project registered for this path' });
+                return;
+            }
+            const context = registry.getContext(project.id);
+            if (!context) {
+                res.status(503).json({ error: 'Project is registered but unavailable', code: 'project_unavailable', project });
+                return;
+            }
+            registry.touchProject(project.id);
+            res.json({ project: context.project });
+        }
+        catch (err) {
+            sendRepositoryError(err, res);
         }
-        registry.touchProject(ctx.project.id);
-        res.json({ project: ctx.project });
     });
     // GET /api/settings — get app-level settings
     router.get('/settings', (_req, res) => {
@@ -1184,6 +1279,11 @@ function createDesktopRouter(registry, broadcast) {
         // and not members of the WsMessage union; cast at this single boundary.
         broadcast: (msg) => broadcast(msg),
         providers: () => registry.installedProvidersUnion(),
+        reseed: version => (0, framework_reseed_1.reseedStaleWorkspaces)(registry.listContexts().map(context => ({
+            id: context.project.id,
+            slug: context.project.slug,
+            path: context.project.path,
+        })), version),
     });
     // GET /api/core-update/status — current/bundled/latest versions, no network.
     router.get('/core-update/status', (_req, res) => {

package/server/dist/dev-ports.js

@@ -24,12 +24,17 @@ function resolveServerPort(argv, env = process.env) {
     return port;
 }
 function resolveWebDevPorts(env = process.env) {
-    const serverPort = parseDevPort(env.SPECRAILS_DEV_SERVER_PORT, exports.DEFAULT_DEV_SERVER_PORT);
+    const serverPort = resolveServerPort([], env);
     const clientPort = parseDevPort(env.SPECRAILS_DEV_CLIENT_PORT, exports.DEFAULT_DEV_CLIENT_PORT);
+    if (serverPort === clientPort) {
+        throw new Error('SPECRAILS_DEV_CLIENT_PORT must differ from the Specrails API port (SPECRAILS_DEV_SERVER_PORT or SPECRAILS_PORT).');
+    }
     return {
         serverPort,
         clientPort,
-        serverOrigin: `http://localhost:${serverPort}`,
-        wsUrl: `ws://localhost:${serverPort}`,
+        // index.ts binds IPv4 loopback. localhost can resolve to another app on ::1
+        // using the same numeric port, including a frontend returning HTML for /api.
+        serverOrigin: `http://127.0.0.1:${serverPort}`,
+        wsUrl: `ws://127.0.0.1:${serverPort}`,
     };
 }