specrails-desktop 2.21.0 → 2.22.0

package/server/dist/rails-store.js

@@ -1,11 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RAILS = exports.BASE_RAIL_COUNT = void 0;
+exports.ensureRailMeta = ensureRailMeta;
+exports.listRailIndices = listRailIndices;
+exports.railCount = railCount;
+exports.railExists = railExists;
 exports.getRails = getRails;
 exports.getRail = getRail;
 exports.setRailTickets = setRailTickets;
 exports.setRailProfile = setRailProfile;
 exports.setRailEngine = setRailEngine;
+exports.createRail = createRail;
+exports.deleteRail = deleteRail;
 exports.setRailName = setRailName;
+/** The three rails every project starts with (indices 0-2, never auto-removed). */
+exports.BASE_RAIL_COUNT = 3;
+/** Hard cap on rails per project — keeps railIndex-keyed maps (metrics,
+ *  pr-deliveries, worktree progress) bounded and the board renderable. */
+exports.MAX_RAILS = 12;
 /** Read the per-rail display names from rail_meta into a lookup map. */
 function railNames(db) {
     const rows = db.prepare('SELECT rail_index, name FROM rail_meta').all();
@@ -14,6 +26,32 @@ function railNames(db) {
         map.set(r.rail_index, r.name);
     return map;
 }
+/** Materialize a rail's identity row (idempotent). rail_meta is the existence
+ *  authority for rails: a rail exists iff it has a rail_meta row (the base
+ *  three are seeded by db migration 39; created rails insert theirs) or any
+ *  leftover ticket rows. Called by every mutation that "touches" a rail so a
+ *  rail the client only knew locally (legacy localStorage rail-4+) becomes
+ *  server-backed the first time it is named / assigned tickets. */
+function ensureRailMeta(db, railIndex) {
+    db.prepare('INSERT OR IGNORE INTO rail_meta (rail_index, name) VALUES (?, NULL)').run(railIndex);
+}
+/** Every existing rail index, ascending: the union of rail_meta identity rows
+ *  and any index that still holds ticket rows (defensive — covers rows written
+ *  before rail_meta materialization existed). */
+function listRailIndices(db) {
+    const rows = db
+        .prepare('SELECT rail_index FROM rail_meta UNION SELECT rail_index FROM rails ORDER BY rail_index')
+        .all();
+    return rows.map((r) => r.rail_index);
+}
+/** How many rails currently exist (>= BASE_RAIL_COUNT unless deleted below it). */
+function railCount(db) {
+    return listRailIndices(db).length;
+}
+/** Whether a rail exists (base rails always do; dynamic rails via rail_meta/rows). */
+function railExists(db, railIndex) {
+    return listRailIndices(db).includes(railIndex);
+}
 // ─── Queries ─────────────────────────────────────────────────────────────────
 function getRails(db) {
     const rows = db
@@ -32,7 +70,10 @@ function getRails(db) {
         map.get(row.rail_index).ticketIds.push(row.ticket_id);
     }
     const names = railNames(db);
-    return [0, 1, 2].map((railIndex) => {
+    // DYNAMIC rail count: every rail with an identity row (rail_meta) or ticket
+    // rows is listed — the base three are seeded, created rails append, deleted
+    // dynamic rails disappear (indices may be sparse after a middle deletion).
+    return listRailIndices(db).map((railIndex) => {
         const rail = map.get(railIndex);
         return {
             railIndex,
@@ -67,6 +108,10 @@ function setRailTickets(db, railIndex, ticketIds, mode, profileName, aiEngine) {
     // undefined → preserve existing engine across re-orders; null → explicit clear.
     const resolvedEngine = aiEngine === undefined ? (getRail(db, railIndex).aiEngine ?? null) : aiEngine;
     db.transaction(() => {
+        // Materialize the rail's identity so a rail first touched by a ticket sync
+        // (e.g. a legacy client-local rail-4+ at launch time) persists server-side
+        // even after its tickets are released.
+        ensureRailMeta(db, railIndex);
         deleteStmt.run(railIndex);
         for (let i = 0; i < ticketIds.length; i++) {
             insertStmt.run(railIndex, ticketIds[i], i, resolvedMode, resolvedProfile, resolvedEngine);
@@ -102,6 +147,38 @@ function setRailEngine(db, railIndex, aiEngine) {
     db.prepare('UPDATE rails SET ai_engine = ? WHERE rail_index = ?').run(aiEngine, railIndex);
     return { ...current, aiEngine };
 }
+/**
+ * Create the next rail (index = highest existing + 1) with an optional display
+ * name. The caller (rails-router / MCP create_rail) enforces the MAX_RAILS cap
+ * — the store itself stays mechanism-only. Returns the new rail's state.
+ */
+function createRail(db, name) {
+    // Lowest free index (not max+1): re-filling a deleted middle rail's slot keeps
+    // indices bounded below MAX_RAILS whenever the COUNT is below the cap. Reuse
+    // is safe — the delete guards ensure a deleted index left no active run or
+    // undecided PR delivery behind.
+    const taken = new Set(listRailIndices(db));
+    let railIndex = 0;
+    while (taken.has(railIndex))
+        railIndex++;
+    const trimmed = typeof name === 'string' ? name.trim() : null;
+    const value = trimmed && trimmed.length > 0 ? trimmed : null;
+    db.prepare('INSERT OR IGNORE INTO rail_meta (rail_index, name) VALUES (?, ?)').run(railIndex, value);
+    return { railIndex, ticketIds: [], mode: 'implement', profileName: null, aiEngine: null, name: value };
+}
+/**
+ * Delete a rail's identity + ticket rows. Pure mechanism — the router enforces
+ * the guards (rail exists, empty, idle, no pending PR decision, not the last
+ * rail). Deleting a middle rail leaves a sparse index gap on purpose: indices
+ * are IDENTITY (metrics / pr-deliveries / worktree maps key by railIndex), so
+ * they are never compacted/re-numbered.
+ */
+function deleteRail(db, railIndex) {
+    db.transaction(() => {
+        db.prepare('DELETE FROM rail_meta WHERE rail_index = ?').run(railIndex);
+        db.prepare('DELETE FROM rails WHERE rail_index = ?').run(railIndex);
+    })();
+}
 /**
  * Set a rail's display name (the "Rail "-suffix the user types). Stored in
  * rail_meta (ticket-independent) so even an empty rail keeps its name. Pass

package/server/dist/setup-prerequisites.js

@@ -137,6 +137,7 @@ function getBundledToolCandidates(runtimesBase, tool) {
             npm: [path_1.default.join(runtimesBase, 'node', 'npm.cmd')],
             npx: [path_1.default.join(runtimesBase, 'node', 'npx.cmd')],
             git: [path_1.default.join(runtimesBase, 'git', 'cmd', 'git.exe'), path_1.default.join(runtimesBase, 'git', 'bin', 'git.exe')],
+            gh: [path_1.default.join(runtimesBase, 'gh', 'bin', 'gh.exe')],
         };
         return map[tool];
     }
@@ -145,6 +146,7 @@ function getBundledToolCandidates(runtimesBase, tool) {
         npm: [path_1.default.join(runtimesBase, 'node', 'bin', 'npm')],
         npx: [path_1.default.join(runtimesBase, 'node', 'bin', 'npx')],
         git: [path_1.default.join(runtimesBase, 'git', 'bin', 'git')],
+        gh: [path_1.default.join(runtimesBase, 'gh', 'bin', 'gh')],
     };
     return map[tool];
 }
@@ -272,6 +274,23 @@ function computeSetupPrerequisitesStatus(options = {}) {
                 ? 'Install Git for Windows and enable the option that adds Git to PATH, then restart Specrails.'
                 : 'Install Git and restart Specrails if PATH changed.',
         },
+        {
+            key: 'gh',
+            kind: 'tool',
+            label: 'GitHub CLI',
+            command: 'gh',
+            // Optional: the app degrades gracefully without gh (the PR-delivery flow
+            // reports local-only/pushed instead of creating the PR) — never blocks
+            // Add Project. Desktop builds bundle a fallback gh; the system one wins
+            // when installed (it carries the user's auth/hosts config).
+            required: false,
+            installUrl: 'https://cli.github.com',
+            installHint: process.platform === 'win32'
+                ? 'Install GitHub CLI via winget (`winget install GitHub.cli`), run `gh auth login`, then restart Specrails.'
+                : process.platform === 'darwin'
+                    ? 'Install GitHub CLI via Homebrew (`brew install gh`), run `gh auth login`, then restart Specrails.'
+                    : 'Install GitHub CLI (https://cli.github.com), run `gh auth login`, then restart Specrails.',
+        },
     ];
     // Provider CLIs (one entry per registered adapter). Individually `required:
     // false` — the "at least one provider" rule is enforced at the bottom of
@@ -305,6 +324,11 @@ function computeSetupPrerequisitesStatus(options = {}) {
         });
     }
     const prerequisites = definitions.map((definition) => {
+        // gh is SYSTEM-FIRST with a bundled fallback (the inverse of node/git):
+        // the user's own gh must win because it carries their auth/hosts config.
+        if (definition.key === 'gh') {
+            return probeGhPrerequisite(definition, isDesktop, runtimesBase);
+        }
         // Desktop mode: probe bundled absolute paths for node/npm/npx/git.
         // Provider CLIs (claude, codex) are always probed via system PATH regardless of mode.
         if (isDesktop && definition.kind === 'tool' && isBundledTool(definition.key)) {
@@ -402,6 +426,87 @@ function computeSetupPrerequisitesStatus(options = {}) {
         missingRequired,
     };
 }
+/** Offline auth check: `gh auth token` exits 0 iff a credential exists for the
+ *  default host. No network (unlike `gh auth status`, which validates the token
+ *  against the API and would misreport "not signed in" offline). The token
+ *  value is intentionally never read. */
+function probeGhAuthenticated(ghBin) {
+    const result = runVersionSpawn(ghBin, ['auth', 'token'], VERSION_PROBE_TIMEOUT_MS);
+    return !result.error && (result.status ?? 1) === 0;
+}
+/**
+ * gh probe order — the INVERSE of node/git:
+ *   1. System PATH (`which gh`) — the user's install always wins (their
+ *      auth/hosts config, GHES setups, aliases live there).
+ *   2. Desktop bundled fallback (`runtimes/gh/bin/gh[.exe]`) — only when no
+ *      system gh resolves. File exists but fails its probe → corrupted-bundle
+ *      (same semantics as node/git).
+ * Either way, an executable gh also reports `authenticated` (bundling removes
+ * the INSTALL step, not the `gh auth login` step — the config at ~/.config/gh
+ * is shared by any gh binary, so a system login carries over to the bundled
+ * one automatically).
+ */
+function probeGhPrerequisite(definition, isDesktop, runtimesBase) {
+    // 1. System probe.
+    const lookup = locateCommand(definition.command);
+    if (lookup.found) {
+        const probe = probeVersion(definition.command, lookup.resolvedPath);
+        const executable = probe.executed;
+        return {
+            ...definition,
+            installed: true,
+            executable,
+            version: probe.version,
+            resolvedPath: lookup.resolvedPath,
+            executionError: probe.error,
+            meetsMinimum: executable && meetsMinimumVersion(probe.version, definition.minVersion),
+            installHint: executable
+                ? definition.installHint
+                : brokenSymlinkHint(definition.label, definition.command, lookup.resolvedPath),
+            ...(executable && lookup.resolvedPath
+                ? { authenticated: probeGhAuthenticated(lookup.resolvedPath) }
+                : {}),
+        };
+    }
+    // 2. Bundled fallback (desktop mode only, existence-gated).
+    if (isDesktop && runtimesBase) {
+        const bundledPath = getBundledToolCandidates(runtimesBase, 'gh').find(fileExists);
+        if (bundledPath) {
+            const probe = probeVersion('gh', bundledPath);
+            if (!probe.executed) {
+                return {
+                    ...definition,
+                    installed: true,
+                    executable: false,
+                    bundled: true,
+                    error: 'corrupted-bundle',
+                    resolvedPath: bundledPath,
+                    executionError: probe.error,
+                    meetsMinimum: false,
+                    installHint: 'Bundle corrupted — reinstall the Specrails app.',
+                };
+            }
+            return {
+                ...definition,
+                installed: true,
+                executable: true,
+                bundled: true,
+                version: probe.version,
+                resolvedPath: bundledPath,
+                meetsMinimum: meetsMinimumVersion(probe.version, definition.minVersion),
+                installHint: '',
+                authenticated: probeGhAuthenticated(bundledPath),
+            };
+        }
+    }
+    // Neither system nor bundled gh present.
+    return {
+        ...definition,
+        installed: false,
+        executable: false,
+        meetsMinimum: false,
+    };
+}
 // ─── Provider install hints ────────────────────────────────────────────────
 function providerInstallUrl(id) {
     switch (id) {

package/server/dist/smash-runner.js

@@ -353,7 +353,9 @@ function applySmashUndo(filePath, epicId, smashedAt, nowIso) {
         // Restore the pre-SMASH status from metadata if available.
         // B61: 'done' was missing from this whitelist, so undoing a SMASH on a ticket
         // that was 'done' before silently demoted it to 'todo'. Include every valid
-        // non-epic status.
+        // non-epic status. 'on_review' is DELIBERATELY excluded: it is a transient
+        // rail-settle state owned by the PR-decision flow — an undo cannot resurrect
+        // the delivery it belonged to, so it falls back to 'todo' (pinned by test).
         const md = (target.metadata ?? {});
         if (md.pre_smash_status === 'todo' || md.pre_smash_status === 'in_progress'
             || md.pre_smash_status === 'cancelled' || md.pre_smash_status === 'draft'

package/server/dist/ticket-store.js

@@ -19,7 +19,7 @@ exports.isValidPriority = isValidPriority;
 exports.validatePriorityForStatus = validatePriorityForStatus;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const VALID_STATUSES = new Set(['draft', 'todo', 'in_progress', 'done', 'cancelled']);
+const VALID_STATUSES = new Set(['draft', 'todo', 'in_progress', 'on_review', 'done', 'cancelled']);
 const VALID_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
 exports.CURRENT_SCHEMA_VERSION = '1.3';
 exports.SHORT_SUMMARY_MAX_LEN = 240;
@@ -327,12 +327,16 @@ function writeStore(filePath, store) {
  *
  * - `completed`: promote `todo`/`in_progress` → `done` (never resurrect a `draft`
  *   or a `cancelled` spec into Done); clear any stale `needs_review` flag.
+ *   When `opts.completedStatus` is `'on_review'` (the ask-first PR-delivery
+ *   path), the same promotable set moves to `on_review` instead of `done` —
+ *   the spec only reaches Done once the delivered PR merges. The default
+ *   `'done'` is byte-identical to the legacy behaviour.
  * - `failed`/`canceled`/`zombie_terminated`: revert an `in_progress` spec → `todo`
  *   (back to the Specs column). If the agent had already marked it `done` (its
  *   Ship phase ran, then the process died), keep it `done` but set `needs_review`
  *   so the board flags it for review.
  */
-function applyJobOutcomeToTickets(store, ticketIds, outcome, now) {
+function applyJobOutcomeToTickets(store, ticketIds, outcome, now, opts) {
     const changed = [];
     for (const tid of ticketIds) {
         const ticket = store.tickets[String(tid)];
@@ -344,7 +348,7 @@ function applyJobOutcomeToTickets(store, ticketIds, outcome, now) {
             if (!promotable && !clearWarning)
                 continue;
             if (promotable)
-                ticket.status = 'done';
+                ticket.status = opts?.completedStatus ?? 'done';
             if (clearWarning)
                 delete ticket.needs_review;
             ticket.updated_at = now;

package/server/dist/workspace-resolution.js

@@ -36,6 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isWorkspacePopulated = isWorkspacePopulated;
 exports.resolveProjectExecution = resolveProjectExecution;
+exports.resolveLoopBaseEnv = resolveLoopBaseEnv;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const artifact_registry_1 = require("./artifact-registry");
@@ -127,6 +128,32 @@ function resolveProjectExecution(project, home) {
         env,
     };
 }
+/**
+ * Base spawn env for a project's LOOP executors (rails / custom loops).
+ *
+ * Relocated projects need core's env-first artifact indirection
+ * (`SPECRAILS_TICKETS_PATH` / `SPECRAILS_BACKLOG_CONFIG_PATH` /
+ * `SPECRAILS_PROFILES_DIR` / `SPECRAILS_STATE_DIR` / `SPECRAILS_WORKSPACE_DIR`
+ * → the workspace) even when the spawn cwd is NOT the workspace: an ISOLATED
+ * rail spawns from its git WORKTREE, where the cwd-relative `${ENV:-legacy}`
+ * defaults would resolve to nothing (`git worktree add` materializes only
+ * tracked files). In particular `SPECRAILS_BACKLOG_CONFIG_PATH` MUST reach core
+ * so it never falls through to its default `write_access:true` branch.
+ *
+ * `SPECRAILS_REPO_DIR` is intentionally OMITTED: it is PER-RUN (the worktree
+ * for isolated runs — writes/git must land there — vs the repo for shared
+ * runs) and is injected by the executors from each run's `repoDir`. Leaving it
+ * here would leak the LIVE repo path into isolated shell steps.
+ *
+ * Legacy projects return `process.env` untouched — byte-identical behaviour.
+ */
+function resolveLoopBaseEnv(project, home) {
+    const exec = resolveProjectExecution(project, home);
+    if (!exec.relocated)
+        return process.env;
+    const { SPECRAILS_REPO_DIR: _perRun, ...projectEnv } = exec.env;
+    return { ...process.env, ...projectEnv };
+}
 /** Build the legacy (in-repo, byte-identical-to-today) execution. */
 function legacyExecution(repoDir) {
     const specrailsDir = path_1.default.join(repoDir, '.specrails');

package/server/dist/worktree-manager.js

@@ -41,12 +41,15 @@ exports.worktreePath = worktreePath;
 exports.createWorktree = createWorktree;
 exports.commitWorktree = commitWorktree;
 exports.removeWorktree = removeWorktree;
+exports.listLocalBranches = listLocalBranches;
 exports.listWorktrees = listWorktrees;
 /**
  * Git worktree lifecycle for parallel-rail isolation. Each isolated ticket run
- * gets its own worktree on branch `sr/<slug>/ticket-<id>` off the repo HEAD, so
+ * gets its own worktree on its own branch off the integration base, so
  * concurrent AI CLIs never collide on a shared working tree; the merge-manager
- * later integrates the branches back.
+ * later integrates the branches back. The caller passes the conventional
+ * branch name (`<type>/<ref>-<kebab-title>`, see pr-naming.ts); when absent
+ * the legacy `sr/<slug>/ticket-<id>` fallback is used.
  *
  * All git I/O goes through an injectable `GitRunner` so the logic is unit-tested
  * without a real repository. Worktrees live under `$HOME` (never in the repo) and
@@ -86,7 +89,8 @@ async function repoIsolationStatus(git, dir) {
     const head = await git.run(['rev-parse', '--verify', '--quiet', 'HEAD'], dir);
     return head.code === 0 ? 'ok' : 'no-commits';
 }
-/** Stable branch name for a ticket's isolated run. */
+/** Legacy fallback branch name for a ticket's isolated run (used only when the
+ *  caller does not pass a conventional preferred name — see pr-naming.ts). */
 function worktreeBranch(slug, ticketId) {
     return `sr/${slug}/ticket-${ticketId}`;
 }
@@ -100,7 +104,7 @@ function worktreePath(worktreesRoot, ticketId) {
  * fall back to the shared-cwd path for that ticket.
  */
 async function createWorktree(git, input) {
-    const branch = worktreeBranch(input.slug, input.ticketId);
+    const branch = input.branch ?? worktreeBranch(input.slug, input.ticketId);
     const wt = worktreePath(input.worktreesRoot, input.ticketId);
     const base = input.baseRef ?? 'HEAD';
     // RESUME-AWARE (idempotency): a re-launched rail must pick up the partial work
@@ -111,7 +115,16 @@ async function createWorktree(git, input) {
     //  3. neither → create a fresh branch off base.
     const existing = await listWorktrees(git, input.repoDir);
     if (existing.some((p) => path.resolve(p) === path.resolve(wt))) {
-        return { branch, worktreePath: wt };
+        // The still-mounted worktree may be checked out on a DIFFERENT branch than
+        // the caller's preferred name (the path is keyed by ticketId only, so a
+        // stale mount from a prior run of the same ticket collides here). The
+        // handle MUST report the branch that will actually carry the run's commits
+        // — reporting the caller's preferred name recorded a branch that never
+        // existed, so the later `git push` had no ref and the PR delivery wedged
+        // at local-only. Detached HEAD / a git failure falls back to the input.
+        const head = await git.run(['rev-parse', '--abbrev-ref', 'HEAD'], wt);
+        const actual = head.code === 0 ? head.stdout.trim() : '';
+        return { branch: actual && actual !== 'HEAD' ? actual : branch, worktreePath: wt };
     }
     const hasBranch = (await git.run(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], input.repoDir)).code === 0;
     const args = hasBranch
@@ -128,9 +141,19 @@ async function createWorktree(git, input) {
  * git — it survives worktree removal, is mergeable by the merge-back, and lets a
  * re-launched rail resume from it. No-op (the commit just exits non-zero) when
  * there is nothing to commit. Best-effort: never throws.
+ *
+ * `excludePaths` (worktree-relative, POSIX separators) are skipped via
+ * `:(exclude)` pathspecs — the per-run overlay (worktree-overlay.ts) threads its
+ * app-owned scaffolding (framework symlinks, `.mcp.json` copy, manifest) here so
+ * it NEVER lands on the ticket branch / PR. All excluded paths are untracked by
+ * construction (the overlay only creates entries the checkout lacked), so
+ * excluding them can never drop real work.
  */
-async function commitWorktree(git, worktreePath, message) {
-    await git.run(['add', '-A'], worktreePath).catch(() => { });
+async function commitWorktree(git, worktreePath, message, excludePaths = []) {
+    const addArgs = excludePaths.length > 0
+        ? ['add', '-A', '--', '.', ...excludePaths.map((p) => `:(exclude)${p}`)]
+        : ['add', '-A'];
+    await git.run(addArgs, worktreePath).catch(() => { });
     await git.run(['commit', '-m', message], worktreePath).catch(() => { });
 }
 /** Remove a worktree (force) and optionally delete its branch. Best-effort — a
@@ -141,6 +164,18 @@ async function removeWorktree(git, input) {
         await git.run(['branch', '-D', input.branch], input.repoDir);
     }
 }
+/** Every local branch name (`git for-each-ref refs/heads/`) — the collision
+ *  input for conventional branch naming. A git failure returns an empty set
+ *  (the caller then trusts the preferred names; worktree add still guards). */
+async function listLocalBranches(git, repoDir) {
+    const res = await git.run(['for-each-ref', '--format=%(refname:short)', 'refs/heads/'], repoDir);
+    if (res.code !== 0)
+        return new Set();
+    return new Set(res.stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter(Boolean));
+}
 /** Parse `git worktree list --porcelain` into the worktree paths it reports
  *  (excluding the main working tree, which is `repoDir` itself). */
 async function listWorktrees(git, repoDir) {