specrails-desktop 2.24.0 → 2.24.2

package/server/dist/active-pr-continuation.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveActivePrContinuationTargets = resolveActivePrContinuationTargets;
+const jira_db_1 = require("./jira/jira-db");
+const rail_pr_store_1 = require("./rail-pr-store");
+const integration_branch_1 = require("./integration-branch");
+function parsePrNumber(prUrl) {
+    if (!prUrl)
+        return null;
+    const m = /\/pull\/(\d+)/.exec(prUrl);
+    return m ? parseInt(m[1], 10) : null;
+}
+function normalizedText(v) {
+    return typeof v === 'string' ? v.toLowerCase() : '';
+}
+function words(v) {
+    return normalizedText(v)
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length >= 4);
+}
+function ticketRefs(db, ticketId, spec) {
+    const refs = new Set([`#${ticketId}`, `[${ticketId}]`, `ticket ${ticketId}`, `spec ${ticketId}`]);
+    let jiraKey = spec?.jira_key ?? null;
+    try {
+        const link = (0, jira_db_1.getLinkByLocalId)(db, ticketId);
+        if (link && !link.tombstoned && link.jiraKey)
+            jiraKey = link.jiraKey;
+    }
+    catch {
+        /* tolerated */
+    }
+    if (jiraKey?.trim())
+        refs.add(jiraKey.trim());
+    return [...refs];
+}
+function hasJiraRef(db, ticketId, spec) {
+    if (spec?.jira_key?.trim())
+        return true;
+    try {
+        const link = (0, jira_db_1.getLinkByLocalId)(db, ticketId);
+        return Boolean(link && !link.tombstoned && link.jiraKey);
+    }
+    catch {
+        return false;
+    }
+}
+function prMatchKind(db, ticketId, spec, pr) {
+    const haystack = `${pr.title ?? ''}\n${pr.body ?? ''}\n${pr.headRefName ?? ''}`.toLowerCase();
+    for (const ref of ticketRefs(db, ticketId, spec)) {
+        const needle = ref.toLowerCase();
+        if (needle.startsWith('#') || needle.startsWith('[')) {
+            if (haystack.includes(needle))
+                return 'explicit-ref';
+        }
+        else if (new RegExp(`(^|[^a-z0-9])${needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^a-z0-9]|$)`, 'i').test(haystack)) {
+            return 'explicit-ref';
+        }
+    }
+    const titleWords = words(spec?.title);
+    if (titleWords.length < 3)
+        return null;
+    const prWords = new Set(words(`${pr.title ?? ''} ${pr.body ?? ''}`));
+    const hits = titleWords.filter((w) => prWords.has(w)).length;
+    return hits >= Math.max(3, Math.ceil(titleWords.length * 0.7)) ? 'title-similarity' : null;
+}
+function canProbeGithubForContinuation(db, ticketId, spec) {
+    if (spec?.status === 'on_review')
+        return true;
+    // Jira review can materialize as in_progress when the project has not mapped
+    // its exact Review status to Specrails on_review. In that fallback, require a
+    // Jira-linked ticket and later only accept explicit PR references.
+    return spec?.status === 'in_progress' && hasJiraRef(db, ticketId, spec);
+}
+function matchAllowedForTicket(spec, kind) {
+    if (spec?.status === 'on_review')
+        return true;
+    return kind === 'explicit-ref';
+}
+async function localBranchExists(git, repoDir, branch) {
+    const r = await git.run(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], repoDir);
+    return r.code === 0;
+}
+async function remoteBranchExists(git, repoDir, branch) {
+    const r = await git.run(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`], repoDir);
+    return r.code === 0;
+}
+async function materializeTarget(git, repoDir, fetchOk, ticketId, branch, baseBranch, prUrl, prNumber, isDraft, source) {
+    const head = branch?.trim();
+    const base = baseBranch?.trim();
+    if (!head || !base || head === base)
+        return null;
+    if (!(0, integration_branch_1.isValidBranchName)(head) || !(0, integration_branch_1.isValidBranchName)(base))
+        return null;
+    if (await localBranchExists(git, repoDir, head)) {
+        return { ticketId, branch: head, baseBranch: base, prUrl, prNumber, isDraft, source };
+    }
+    if (fetchOk && await remoteBranchExists(git, repoDir, head)) {
+        return { ticketId, branch: head, baseBranch: base, baseRef: `origin/${head}`, prUrl, prNumber, isDraft, source };
+    }
+    return null;
+}
+function internalDeliveryTargets(db, ticketIds) {
+    const wanted = new Set(ticketIds);
+    const out = new Map();
+    for (const row of (0, rail_pr_store_1.listActivePrDeliveries)(db)) {
+        const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+        if (!snap.prUrl || !snap.branch)
+            continue;
+        for (const ticketId of snap.ticketIds) {
+            if (!wanted.has(ticketId) || out.has(ticketId))
+                continue;
+            out.set(ticketId, {
+                ticketId,
+                branch: snap.branch,
+                baseBranch: snap.baseBranch,
+                prUrl: snap.prUrl,
+                prNumber: snap.prNumber,
+                isDraft: snap.decision === 'pr_draft',
+                source: 'rail-pr-delivery',
+            });
+        }
+    }
+    return out;
+}
+async function listOpenPrs(exec, repoDir) {
+    const r = await exec.run('gh', ['pr', 'list', '--state', 'open', '--json', 'number,title,body,headRefName,baseRefName,url,isDraft'], repoDir);
+    if (r.code !== 0)
+        return [];
+    try {
+        const parsed = JSON.parse(r.stdout);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Detects tickets whose next implementation pass should continue an already
+ * open PR branch instead of creating fresh work from the integration branch.
+ * It is intentionally fail-open: no gh, no auth, ambiguous branch state, or no
+ * confident PR match all return no target, preserving the normal new-work flow.
+ */
+async function resolveActivePrContinuationTargets(input) {
+    const out = new Map();
+    const internal = internalDeliveryTargets(input.db, input.ticketIds);
+    for (const [ticketId, target] of internal) {
+        const materialized = await materializeTarget(input.git, input.repoDir, input.fetchOk, ticketId, target.branch, target.baseBranch, target.prUrl, target.prNumber, target.isDraft, 'rail-pr-delivery');
+        if (materialized)
+            out.set(ticketId, materialized);
+    }
+    const remaining = input.ticketIds.filter((id) => !out.has(id));
+    const candidateIds = remaining.filter((id) => canProbeGithubForContinuation(input.db, id, input.getTicketSpec(id)));
+    if (candidateIds.length === 0)
+        return out;
+    const openPrs = await listOpenPrs(input.exec, input.repoDir);
+    for (const ticketId of candidateIds) {
+        const spec = input.getTicketSpec(ticketId);
+        const matches = openPrs.filter((pr) => {
+            const kind = prMatchKind(input.db, ticketId, spec, pr);
+            return kind ? matchAllowedForTicket(spec, kind) : false;
+        });
+        if (matches.length !== 1)
+            continue;
+        const pr = matches[0];
+        const materialized = await materializeTarget(input.git, input.repoDir, input.fetchOk, ticketId, pr.headRefName, pr.baseRefName || input.integrationBranch, pr.url ?? null, typeof pr.number === 'number' ? pr.number : parsePrNumber(pr.url), typeof pr.isDraft === 'boolean' ? pr.isDraft : null, 'github-open-pr');
+        if (materialized)
+            out.set(ticketId, materialized);
+    }
+    return out;
+}

package/server/dist/agent-operator-prompt.js

@@ -324,6 +324,13 @@ summary later.
 - Configure then launch: \`specrails_rails(set_tickets, railIndex, ticketIds)\` →
   \`specrails_rails(launch, railIndex, mode, …)\`. Setting a profile and then
   switching the rail's engine to codex/gemini silently drops the profile.
+- When relaunching an \`on_review\` spec that already has an OPEN GitHub PR,
+  \`launch\` automatically tries to continue that PR's head branch (matched by
+  Jira key / spec id / title) instead of starting from the integration branch.
+  Jira-linked \`in_progress\` specs can also continue an open PR when the match
+  is explicit, covering Jira projects whose Review status has not been mapped to
+  Specrails \`on_review\`. You do NOT need to know or pass the branch name. If
+  there is no confident open PR match, the normal new-work flow is preserved.
 - Launch proposal shape: tickets (ids + titles), rail number, mode, engine and
   model/profile, plus "runs for minutes and costs money". Wait for yes.
 - **Parallel launches are safe and normal.** Every rail launch runs its work in
@@ -362,6 +369,8 @@ summary later.
   folder is not a git repo; \`no-commits\` = git repo with no initial commit;
   \`error\` = isolation failed, relay the detail), and — for no-git/no-commits —
   that \`git init\` + one commit (no GitHub remote needed) unlocks the PR flow.
+  In no-git/no-commits projects, there is also no active-PR continuation because
+  there is no branch graph to continue.
   When isolation IS available (no such field), the card WILL appear on settle.
 - **After an ISOLATED rail settles, the DECISION belongs to the user, in the
   app's UI** (the PR card in this chat and the rail header show the same

package/server/dist/claude-trust.js

@@ -36,26 +36,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeConfigPath = claudeConfigPath;
 exports.markProjectsTrusted = markProjectsTrusted;
 exports.ensureClaudeTrusted = ensureClaudeTrusted;
-exports.__resetClaudeTrustMemoForTest = __resetClaudeTrustMemoForTest;
 /**
  * Pre-trust specrails-managed spawn directories in the user's `~/.claude.json`
- * so a HEADLESS claude rail/job spawn honours the `.claude/settings.json`
- * `permissions.allow` list the framework overlay places in the worktree.
- *
- * Why: claude ignores a workspace's `permissions.allow` entries until that
- * project directory has been "trusted" (the interactive trust dialog, or
- * `projects[<dir>].hasTrustDialogAccepted: true` in `~/.claude.json`). specrails
- * spawns claude headlessly in FRESH per-run worktrees / workspaces that were
- * never opened interactively, so every isolated rail run logged
+ * so a HEADLESS claude rail/job spawn does NOT log the noisy
  * "Ignoring N permissions.allow entries … this workspace has not been trusted"
- * and ran with its pre-approved permissions silently dropped. We manage those
- * directories, so pre-marking them trusted is correct and safe.
+ * warning.
+ *
+ * IMPORTANT — this is cosmetic, not load-bearing. Every claude spawn already
+ * carries `--dangerously-skip-permissions` (see `claude-adapter.ts` COMMON_FLAGS),
+ * which bypasses the permission engine entirely — so a workspace's
+ * `.claude/settings.json` `permissions.allow` list is moot on these spawns
+ * whether the dir is trusted or not. Marking the dir trusted only silences the
+ * warning. (It WOULD become functionally load-bearing if we ever dropped
+ * `--dangerously-skip-permissions` and relied on the allow-list.)
+ *
+ * Why re-assert on EVERY spawn (no persistent memo): `~/.claude.json` is a
+ * single ~200KB file holding ALL projects that many concurrent claude processes
+ * rewrite wholesale (each carries its own in-memory snapshot). Our surgical
+ * `true` for one dir is routinely clobbered by another process writing the whole
+ * file back with a stale `false` — a lost update. A one-shot per-process memo
+ * (the old design) therefore left the flag stuck `false` for the rest of the
+ * process lifetime after the first clobber. Re-asserting immediately before each
+ * spawn re-flips a clobbered `false → true` so this spawn reads `true` at
+ * startup. It cannot fully win the race against concurrent whole-file writers,
+ * but the failure mode is only a cosmetic warning, so best-effort is enough.
  *
  * Surgical + best-effort: read → set only `hasTrustDialogAccepted` on the
  * relevant `projects[<realpath>]` keys → atomic temp+rename. Never throws, never
  * touches any other field, and only writes when something actually changed.
- * claude-only (the trust/allow model is a claude concept). Memoized per path so
- * a multi-step run does the I/O once, before the first spawn in that dir.
+ * claude-only (the trust/allow model is a claude concept).
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -122,17 +131,21 @@ function markProjectsTrusted(configPath, dirs) {
     }
     return changed;
 }
-// Per-path memo so a multi-step run writes at most once per unique dir.
-const _trusted = new Set();
 /**
- * Ensure the claude spawn directories are trusted, once per process per dir.
- * No-op for non-claude providers and best-effort otherwise (a failure only
- * means the pre-approved permissions stay dropped — never blocks a spawn).
+ * Ensure the claude spawn directories are trusted, RE-ASSERTED on every call
+ * (no persistent memo — see the module header for why: concurrent whole-file
+ * writers clobber our flag back to `false`, and a one-shot memo would leave it
+ * stuck). No-op for non-claude providers and best-effort otherwise (a failure
+ * only leaves the cosmetic trust warning — never blocks a spawn).
+ *
+ * `markProjectsTrusted` reads the current on-disk value and writes ONLY when a
+ * dir is missing / `false`, so a call where the flag is already `true` is a
+ * cheap read with no write.
  */
 function ensureClaudeTrusted(provider, dirs, home) {
     if (provider !== 'claude')
         return;
-    const todo = dirs.filter((d) => !!d && !_trusted.has(canonical(d)));
+    const todo = dirs.filter((d) => !!d);
     if (todo.length === 0)
         return;
     try {
@@ -141,10 +154,4 @@ function ensureClaudeTrusted(provider, dirs, home) {
     catch {
         /* best-effort */
     }
-    for (const d of todo)
-        _trusted.add(canonical(d));
-}
-/** Test-only: clear the per-path memo. */
-function __resetClaudeTrustMemoForTest() {
-    _trusted.clear();
 }

package/server/dist/docs-router.js

@@ -95,13 +95,78 @@ function langDir(guideRoot, lang) {
 }
 // ─── Category configuration ─────────────────────────────────────────────────
 const CATEGORY_LABELS = {
-    'getting-started': 'Getting started',
-    specs: 'Specs',
-    pipeline: 'Pipeline',
-    agents: 'Agents',
-    insights: 'Insights',
-    integrations: 'Integrations',
-    settings: 'Settings',
+    en: {
+        'getting-started': 'Getting started',
+        specs: 'Specs',
+        pipeline: 'Pipeline',
+        agents: 'Agents',
+        insights: 'Insights',
+        integrations: 'Integrations',
+        settings: 'Settings',
+    },
+    es: {
+        'getting-started': 'Primeros pasos',
+        specs: 'Specs',
+        pipeline: 'Pipeline',
+        agents: 'Agentes',
+        insights: 'Insights',
+        integrations: 'Integraciones',
+        settings: 'Ajustes',
+    },
+    fr: {
+        'getting-started': 'Bien démarrer',
+        specs: 'Specs',
+        pipeline: 'Pipeline',
+        agents: 'Agents',
+        insights: 'Insights',
+        integrations: 'Intégrations',
+        settings: 'Réglages',
+    },
+    de: {
+        'getting-started': 'Erste Schritte',
+        specs: 'Specs',
+        pipeline: 'Pipeline',
+        agents: 'Agenten',
+        insights: 'Insights',
+        integrations: 'Integrationen',
+        settings: 'Einstellungen',
+    },
+    pt: {
+        'getting-started': 'Primeiros passos',
+        specs: 'Specs',
+        pipeline: 'Pipeline',
+        agents: 'Agentes',
+        insights: 'Insights',
+        integrations: 'Integrações',
+        settings: 'Definições',
+    },
+    it: {
+        'getting-started': 'Primi passi',
+        specs: 'Spec',
+        pipeline: 'Pipeline',
+        agents: 'Agenti',
+        insights: 'Insights',
+        integrations: 'Integrazioni',
+        settings: 'Impostazioni',
+    },
+    zh: {
+        'getting-started': '入门',
+        specs: '规格',
+        pipeline: '流水线',
+        agents: '代理',
+        insights: '洞察',
+        integrations: '集成',
+        settings: '设置',
+    },
+    ja: {
+        'getting-started': 'はじめに',
+        specs: 'スペック',
+        pipeline: 'パイプライン',
+        agents: 'エージェント',
+        insights: 'インサイト',
+        integrations: '連携',
+        settings: '設定',
+    },
 };
 /**
  * Preferred display order. Categories not in this list come after, alphabetically.
@@ -119,8 +184,8 @@ const CATEGORY_ORDER = [
 function slugToTitle(slug) {
     return slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
 }
-function categoryLabel(slug) {
-    return CATEGORY_LABELS[slug] ?? slugToTitle(slug);
+function categoryLabel(slug, lang) {
+    return CATEGORY_LABELS[lang]?.[slug] ?? CATEGORY_LABELS[DEFAULT_LANG]?.[slug] ?? slugToTitle(slug);
 }
 function extractTitle(content, slug) {
     const match = content.match(/^#\s+(.+)$/m);
@@ -190,7 +255,7 @@ function buildCategories(guideRoot, lang) {
             return { title, slug: meta.slug };
         });
         if (docs.length > 0) {
-            categories.push({ name: categoryLabel(cat), slug: cat, docs });
+            categories.push({ name: categoryLabel(cat, lang), slug: cat, docs });
         }
     }
     return categories.sort((a, b) => categoryRank(a.slug) - categoryRank(b.slug) || a.slug.localeCompare(b.slug));

package/server/dist/integration-branch.js

@@ -1,9 +1,57 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FETCH_ORIGIN_TTL_MS = void 0;
+exports.__resetFetchOriginCache = __resetFetchOriginCache;
+exports.fetchOrigin = fetchOrigin;
 exports.repoDefaultBranch = repoDefaultBranch;
 exports.currentBranch = currentBranch;
 exports.isValidBranchName = isValidBranchName;
 exports.resolveIntegrationBranch = resolveIntegrationBranch;
+exports.resolveWorktreeBaseRef = resolveWorktreeBaseRef;
+/** How long a fetch outcome (success OR failure) is reused for the same repo
+ *  before a fresh `git fetch origin` is attempted again. Exists so a burst of
+ *  near-simultaneous launches against the SAME repo — e.g. a "Launch all"
+ *  batch, which is N independent HTTP requests with no shared server-side
+ *  transaction (see design.md Decision 2) — performs one real fetch instead of
+ *  one per rail. */
+exports.FETCH_ORIGIN_TTL_MS = 15_000;
+const fetchCache = new Map();
+/** Test-only: clear the fetch dedup cache so tests never leak state across
+ *  cases (mirrors `__resetRepoLocks` in repo-lock.ts). */
+function __resetFetchOriginCache() {
+    fetchCache.clear();
+}
+/**
+ * `git fetch origin` against `repoDir` — updates ONLY `refs/remotes/origin/*`,
+ * never the checked-out local branch or working tree (Git itself refuses to
+ * touch either via a plain fetch). Never throws: any non-zero exit or runner
+ * rejection resolves to `{ ok: false, error }` so callers can degrade
+ * gracefully instead of failing the launch.
+ *
+ * De-duped per `repoDir` for `FETCH_ORIGIN_TTL_MS`: a call within the window
+ * of the last attempt (success OR failure) for the same repo reuses that
+ * outcome instead of spawning a new `git fetch` process. `now` is injectable
+ * so tests can control TTL expiry without real timers.
+ */
+async function fetchOrigin(git, repoDir, now = Date.now) {
+    const cached = fetchCache.get(repoDir);
+    const nowMs = now();
+    if (cached && nowMs - cached.at < exports.FETCH_ORIGIN_TTL_MS)
+        return cached.result;
+    const result = (async () => {
+        try {
+            const r = await git.run(['fetch', 'origin'], repoDir);
+            if (r.code === 0)
+                return { ok: true };
+            return { ok: false, error: r.stderr.trim() || r.stdout.trim() || `exit ${r.code}` };
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    })();
+    fetchCache.set(repoDir, { at: nowMs, result });
+    return result;
+}
 /** The repo's default branch via `origin/HEAD` → the bare branch name, or null. */
 async function repoDefaultBranch(git, repoDir) {
     const r = await git.run(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], repoDir);
@@ -61,3 +109,35 @@ async function resolveIntegrationBranch(git, input) {
     // Detached / no remote / unresolvable → the literal HEAD (legacy-identical).
     return { branch: 'HEAD', source: 'head-fallback' };
 }
+/**
+ * Decide the actual `baseRef` a worktree should branch from, given the
+ * already-resolved integration branch and whether `fetchOrigin` succeeded.
+ *
+ * `explicit` is a launch-time override the caller chose on purpose — it is
+ * NEVER remote-prefixed and NEVER existence-checked (see proposal.md Out of
+ * Scope). Every other source (`repo-default`, `project-setting`,
+ * `head-fallback`) uses the fetched remote-tracking ref `origin/<branch>`
+ * ONLY when the fetch succeeded AND that remote branch actually exists —
+ * guards a `project-setting` branch that was never pushed, which would
+ * otherwise turn a working local-only setup into a broken `git worktree add`.
+ * Any failure of either check falls back to today's bare local branch name,
+ * with a human-readable `warning` the caller can log/broadcast.
+ */
+async function resolveWorktreeBaseRef(git, input) {
+    const { repoDir, integration, fetchOk } = input;
+    if (integration.source === 'explicit') {
+        return { baseRef: integration.branch, usedRemote: false };
+    }
+    if (!fetchOk) {
+        return { baseRef: integration.branch, usedRemote: false, warning: 'git fetch origin failed; using local ref' };
+    }
+    const exists = await git.run(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${integration.branch}`], repoDir);
+    if (exists.code === 0) {
+        return { baseRef: `origin/${integration.branch}`, usedRemote: true };
+    }
+    return {
+        baseRef: integration.branch,
+        usedRemote: false,
+        warning: `origin/${integration.branch} not found; using local ref`,
+    };
+}

package/server/dist/jira/jira-adf.js

@@ -12,6 +12,7 @@ exports.bodyForDeployment = bodyForDeployment;
 exports.commentMarker = commentMarker;
 exports.discardCommentMarker = discardCommentMarker;
 exports.prMergedCommentMarker = prMergedCommentMarker;
+exports.railReviewCommentMarker = railReviewCommentMarker;
 exports.bodyContainsMarker = bodyContainsMarker;
 exports.commentHasMarker = commentHasMarker;
 exports.adfToText = adfToText;
@@ -62,6 +63,13 @@ function discardCommentMarker(ticketId, nonce) {
 function prMergedCommentMarker(refId, ticketId) {
     return `[specrails:pr-merged=${refId}:ticket=${ticketId}]`;
 }
+/**
+ * Idempotency marker for the "ready for review" comment posted when an isolated
+ * rail parks a Jira-linked ticket on_review awaiting the PR decision.
+ */
+function railReviewCommentMarker(refId, ticketId) {
+    return `[specrails:rail-review=${refId}:ticket=${ticketId}]`;
+}
 /** True when an ADF doc or wiki string already contains the given marker. */
 function bodyContainsMarker(body, marker) {
     if (typeof body === 'string')

package/server/dist/jira/jira-sync-manager.js

@@ -13,6 +13,7 @@ exports.JiraSyncManager = void 0;
 exports.backoffMs = backoffMs;
 exports.formatJqlDate = formatJqlDate;
 exports.buildCompletionComment = buildCompletionComment;
+exports.buildRailReviewComment = buildRailReviewComment;
 exports.buildPrMergedComment = buildPrMergedComment;
 const node_crypto_1 = require("node:crypto");
 const ticket_store_1 = require("../ticket-store");
@@ -557,6 +558,16 @@ class JiraSyncManager {
                 const link = (0, jira_db_1.getLinkByLocalId)(this.db, localId);
                 if (!link || link.tombstoned)
                     continue;
+                ops.push({
+                    jiraIssueId: link.jiraIssueId,
+                    opType: 'comment',
+                    idempotencyKey: `${refId}:${localId}:comment:on-review`,
+                    payload: {
+                        jiraIssueId: link.jiraIssueId,
+                        text: buildRailReviewComment(link.jiraKey),
+                        marker: (0, jira_adf_1.railReviewCommentMarker)(refId, localId),
+                    },
+                });
                 ops.push({
                     jiraIssueId: link.jiraIssueId,
                     opType: 'transition',
@@ -1144,31 +1155,59 @@ function formatJqlDate(ms) {
     return `${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ${p(d.getUTCHours())}:${p(d.getUTCMinutes())}`;
 }
 function buildCompletionComment(args, jiraKey, needsReview) {
+    const issue = jiraKey?.trim() ? jiraKey.trim() : 'the linked Jira issue';
     if (needsReview) {
-        return 'Specrails: the implementation rail terminated abnormally after its Ship phase — the result needs review.';
+        return [
+            `Specrails rail finished for ${issue}.`,
+            'Result: needs human review.',
+            'The implementation reached its Ship phase, but the rail terminated abnormally before Specrails could fully close the run.',
+            `Run: ${args.jobId}`,
+            'Jira status: left unchanged for review.',
+        ].join('\n');
     }
     const parts = [];
     if (args.status === 'completed') {
-        parts.push('✅ Implementation completed by a Specrails rail.');
+        parts.push(`Specrails rail finished for ${issue}.`);
+        parts.push('Result: completed successfully.');
+        parts.push('Jira status: moving to Done.');
     }
     else if (args.status === 'canceled') {
-        parts.push('⏹️ The Specrails implementation rail was cancelled — the spec was returned to the backlog.');
+        parts.push(`Specrails rail finished for ${issue}.`);
+        parts.push('Result: cancelled before completion.');
+        parts.push('Jira status: returning to the backlog.');
     }
     else {
-        parts.push('❌ The Specrails implementation rail failed — the spec was returned to the backlog.');
+        parts.push(`Specrails rail finished for ${issue}.`);
+        parts.push('Result: failed before completion.');
+        parts.push('Jira status: returning to the backlog.');
     }
-    const meta = [`job ${args.jobId}`];
-    if (args.costUsd != null)
-        meta.push(`cost $${args.costUsd.toFixed(2)}`);
+    parts.push(`Run: ${args.jobId}`);
     if (args.durationMs != null)
-        meta.push(`duration ${formatDuration(args.durationMs)}`);
-    parts.push(`(${meta.join(' · ')})`);
+        parts.push(`Duration: ${formatDuration(args.durationMs)}`);
+    if (args.costUsd != null)
+        parts.push(`Cost: $${args.costUsd.toFixed(2)}`);
     return parts.join('\n');
 }
+/** Comment posted when an isolated rail has produced reviewable work. */
+function buildRailReviewComment(jiraKey) {
+    const issue = jiraKey?.trim() ? jiraKey.trim() : 'the linked Jira issue';
+    return [
+        `Specrails rail finished for ${issue}.`,
+        'Result: implementation ready for PR review.',
+        'Jira status: moving to review while the PR decision remains open in Specrails.',
+        'Next step: review the Specrails PR card, then publish/merge or discard the delivery.',
+    ].join('\n');
+}
 /** Comment posted on a linked issue when its delivery PR is merged. */
 function buildPrMergedComment(prUrl) {
-    const base = '✅ Specrails: the delivery PR was merged — the spec shipped to the integration branch.';
-    return prUrl ? `${base}\n${prUrl}` : base;
+    const parts = [
+        'Specrails delivery accepted.',
+        'Result: PR merged into the integration branch.',
+        'Jira status: moving to Done.',
+    ];
+    if (prUrl)
+        parts.push(`PR: ${prUrl}`);
+    return parts.join('\n');
 }
 function formatDuration(ms) {
     const s = Math.round(ms / 1000);

package/server/dist/mcp/guide.js

@@ -108,6 +108,15 @@ heading inside the description); \`labels\`; \`priority\`. Spec content is Engli
   (ai-spawn) launches EVERY rail that has tickets and no active run / pending
   PR decision in one call, each with its stored mode/engine/profile, returning
   per-rail outcomes (launched / skipped with reason / failed).
+- Relaunching an \`on_review\` ticket with a matching OPEN GitHub PR continues
+  that PR's head branch automatically. Jira-linked \`in_progress\` tickets can
+  also continue an open PR when the match is explicit, covering Jira projects
+  whose Review status has not been mapped to Specrails \`on_review\`. New
+  tickets, or tickets without a confident open-PR match, keep the normal
+  branch-from-integration flow.
+- Projects without Git cannot use isolated worktrees or PR continuation. A
+  launch degrades to shared-cwd execution and returns \`isolationUnavailable\`;
+  explain that it writes directly to files and no PR card/branch will appear.
 - Configure: \`set_tickets\` (replaces the assigned set), \`set_profile\` (null =
   legacy), \`set_engine\` (null = project primary), \`set_name\`.
 - Launch modes:

package/server/dist/mcp/tools/rails.js

@@ -29,6 +29,7 @@ function railsTools() {
                 'launch (ai-spawn — spawns claude/codex/gemini CLI job(s) that WRITE CODE, RUN TESTS, COMMIT, and INCUR TOKEN COST; returns 202 with jobId/jobIds/loopRunIds), ' +
                 'launch_all (ai-spawn — launches EVERY rail that has tickets and no active run/pending PR decision, in parallel, using each rail\'s stored mode/engine/profile; returns per-rail outcomes with skip reasons), ' +
                 'stop (destructive — kills all active jobs and loop runs for the rail). ' +
+                'For on_review tickets with an already-open GitHub PR, launch automatically tries to continue that PR head branch; Jira-linked in_progress tickets can do the same when the PR match is explicit; fresh tickets still start from the project integration branch. ' +
                 'When launched from the in-app agent chat without an explicit aiEngine, the engine defaults to your conversation\'s provider (pass aiEngine to override; launch_all always uses each rail\'s stored engine). ' +
                 'NAMING: railIndex is the 0-BASED internal identity; the dashboard shows rails 1-based ("Rail N" = railIndex N-1). When talking to the user, ALWAYS say "Rail <railIndex + 1>" (or the rail\'s custom name) — results include railLabel with the correct user-facing label.',
             hintTier: 'read',
@@ -234,7 +235,7 @@ function railsTools() {
                         return {
                             ...r,
                             railLabel,
-                            hint: `Launch accepted (202) on ${railLabel} (isolated worktree, PR flow active) — tell the user it runs on "${railLabel}" (UI labels are 1-based) and that the PR-decision card will appear here and on the rail header when it settles. Use specrails_watch with the returned loopRunIds to await completion only if asked. Rails run for minutes; pass untilMs up to 600000 and re-watch on timeout.`,
+                            hint: `Launch accepted (202) on ${railLabel} (isolated worktree, PR flow active) — tell the user it runs on "${railLabel}" (UI labels are 1-based). If the assigned spec is on_review with a matching open PR, or is Jira-linked in_progress with an explicit PR match, Specrails continues that PR branch automatically; otherwise it starts a fresh branch from the integration branch. The PR-decision card will appear here and on the rail header when it settles. Use specrails_watch with the returned loopRunIds to await completion only if asked. Rails run for minutes; pass untilMs up to 600000 and re-watch on timeout.`,
                         };
                     }
                     case 'launch_all': {