specrails-desktop 2.23.0 → 2.24.0

package/server/dist/git-diagnostics.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GIT_DIAGNOSTIC_ACTIONS = void 0;
+exports.isGitDiagnosticAction = isGitDiagnosticAction;
+exports.runGitDiagnostic = runGitDiagnostic;
+exports.gitDiagnosticHelp = gitDiagnosticHelp;
+const child_process_1 = require("child_process");
+const file_provenance_1 = require("./file-provenance");
+const win_spawn_1 = require("./util/win-spawn");
+/**
+ * READ-ONLY git / gh diagnostics for a project's repo — the backing for the
+ * `specrails_git` MCP tool. Lets the in-app operator agent answer questions like
+ * "is this repo connected to GitHub?", "what's the remote?", "is gh
+ * authenticated?", "what changed?" through the app's OWN bundled git/gh, instead
+ * of refusing or asking the user to run terminal commands.
+ *
+ * SAFETY: the command list is a FIXED ALLOWLIST — the caller only picks an
+ * action name, never arguments, so no flag/ref/path can be smuggled in. Every
+ * command is read-only (no push/commit/checkout/pr-create). git runs with the
+ * hardened `GIT_EXEC_ENV` (hostile-repo config stripped, prompts disabled); gh
+ * runs with the normal env so it finds the user's `~/.config/gh` auth and the
+ * bundled `gh` on PATH.
+ */
+exports.GIT_DIAGNOSTIC_ACTIONS = [
+    'remote', 'status', 'log', 'diff', 'branch',
+    'gh_repo', 'gh_auth', 'gh_pr_list', 'gh_pr_view',
+];
+function isGitDiagnosticAction(v) {
+    return typeof v === 'string' && exports.GIT_DIAGNOSTIC_ACTIONS.includes(v);
+}
+const SPECS = {
+    remote: { cmd: 'git', args: ['remote', '-v'], help: 'List configured remotes (is the repo linked to GitHub, and where).' },
+    status: { cmd: 'git', args: ['status', '--short', '--branch'], help: 'Branch + short working-tree status.' },
+    log: { cmd: 'git', args: ['log', '--oneline', '--decorate', '-20'], help: 'The last 20 commits.' },
+    diff: { cmd: 'git', args: ['diff', '--stat'], help: 'Uncommitted change summary (diffstat).' },
+    branch: { cmd: 'git', args: ['branch', '-vv'], help: 'Local branches with upstream tracking.' },
+    gh_repo: { cmd: 'gh', args: ['repo', 'view'], help: 'The GitHub repo this checkout is linked to (fails if none / gh unauth).' },
+    gh_auth: { cmd: 'gh', args: ['auth', 'status'], help: 'Whether gh is authenticated, and for which host/account.' },
+    gh_pr_list: { cmd: 'gh', args: ['pr', 'list', '--limit', '30'], help: 'Open pull requests for the repo.' },
+    gh_pr_view: { cmd: 'gh', args: ['pr', 'view'], help: "The current branch's pull request (if any)." },
+};
+const OUTPUT_CAP = 8_000;
+const defaultExec = (cmd, args, cwd) => new Promise((resolve) => {
+    // git: hardened, cwd-pinned env. gh: user env (needs ~/.config/gh auth) with
+    // the Windows shell-critical vars guaranteed present.
+    const env = cmd === 'gh' ? (0, win_spawn_1.windowsSpawnEnv)() : file_provenance_1.GIT_EXEC_ENV;
+    (0, child_process_1.execFile)(cmd, args, { cwd, env, timeout: 15_000, maxBuffer: 8 * 1024 * 1024, windowsHide: true }, (err, stdout, stderr) => {
+        const code = err && typeof err.code === 'number'
+            ? err.code
+            : err ? 1 : 0;
+        resolve({ code, stdout: String(stdout ?? '').trim(), stderr: String(stderr ?? '').trim() });
+    });
+});
+const cap = (s) => (s.length > OUTPUT_CAP ? `${s.slice(0, OUTPUT_CAP)}\n…(truncated)` : s);
+/**
+ * Run one allow-listed read-only diagnostic in `repoDir`. Throws only on an
+ * UNKNOWN action (defence-in-depth; the route validates too); a non-zero exit
+ * (e.g. `gh repo view` with no remote) is a normal result with `ok: false`.
+ */
+async function runGitDiagnostic(action, repoDir, exec = defaultExec) {
+    if (!isGitDiagnosticAction(action)) {
+        throw new Error(`Unknown diagnostic action: ${action}. Allowed: ${exports.GIT_DIAGNOSTIC_ACTIONS.join(', ')}`);
+    }
+    const spec = SPECS[action];
+    const r = await exec(spec.cmd, spec.args, repoDir);
+    return {
+        action,
+        command: `${spec.cmd} ${spec.args.join(' ')}`,
+        ok: r.code === 0,
+        exitCode: r.code,
+        stdout: cap(r.stdout),
+        stderr: cap(r.stderr),
+    };
+}
+/** The action → human help map, for the MCP tool description / discoverability. */
+function gitDiagnosticHelp() {
+    return Object.fromEntries(Object.keys(SPECS).map((a) => [a, SPECS[a].help]));
+}

package/server/dist/loop-command-catalog.js

@@ -78,17 +78,23 @@ exports.LOOP_COMMANDS = [
     {
         name: 'fix',
         label: 'fix',
-        description: 'Refinement step: the verification reported failures — fix ONLY what is needed to make them pass (smallest change, no re-implementing, no unrelated edits). Verification re-runs after.',
+        description: 'Refinement/advance step: the Loop Decider judged the goal not yet met. Read the verification output — if it FAILED, fix the smallest thing; if it PASSED but the feature is incomplete, implement the missing pieces; if genuinely blocked on a human decision, emit LOOP_BLOCKED and stop.',
         ticketScope: 'per-ticket',
+        // NOT a "fix the failures" step: the Decider routes here on ANY not-done
+        // verdict — which includes "verification PASSED but the feature isn't
+        // implemented yet". Assuming a FAIL boxed the agent in (nothing to fix +
+        // "don't re-implement") and spun the loop. This branches on the REAL verify
+        // verdict and gives a first-class BLOCKED escape so a human-decision blocker
+        // halts the loop instead of cycling. See docs/internals + loop-decider.ts.
         template: [
-            'The verification step above reported failures (see VERIFICATION: FAIL and the output before it).',
+            'The Loop Decider judged the goal NOT yet met. First READ the verification output above and act on what it actually says — do not assume it failed:',
             '',
-            'Fix ONLY what is needed to make the failing tests / type-check / lint / build pass:',
-            '- Make the smallest change that resolves the reported failures.',
-            '- Do NOT re-implement the feature from scratch and do NOT touch unrelated code.',
-            '- If a test is wrong, fix the test; if the code is wrong, fix the code.',
+            '- If it reported `VERIFICATION: FAIL`: fix ONLY what is needed to make the failing tests / type-check / lint / build pass — smallest change, no unrelated edits, no re-implementing from scratch.',
+            '- If it reported `VERIFICATION: PASS` but the spec/feature is NOT fully implemented yet: implement the missing pieces now. This is expected — the loop runs the main step once, then keeps advancing the feature here until it is complete. Build the smallest coherent next increment.',
             '',
-            'The verification will run again after this step.',
+            'Do NOT invent scope or silently take a big architectural decision to make the loop stop. If real progress is BLOCKED on a decision only a human can make — ambiguous requirements, a missing/undone prerequisite, or introducing a new external dependency (a new database, service, or SDK) — do NOT guess and do NOT keep re-running: end your reply with a single line `LOOP_BLOCKED: <the one specific question the human must answer>` and stop. The loop will halt and surface it instead of cycling.',
+            '',
+            'Verification will run again after this step (unless you reported LOOP_BLOCKED).',
         ].join('\n'),
     },
     {

package/server/dist/loop-decider.js

@@ -12,7 +12,7 @@ exports.DECIDER_PROMPT_VERSION = void 0;
 exports.buildDeciderSystemPrompt = buildDeciderSystemPrompt;
 exports.buildDeciderUserPrompt = buildDeciderUserPrompt;
 exports.parseDeciderDecision = parseDeciderDecision;
-exports.DECIDER_PROMPT_VERSION = 2;
+exports.DECIDER_PROMPT_VERSION = 3;
 /** Byte-stable system prompt (no timestamps/aggregates) so prompt caching hits. */
 function buildDeciderSystemPrompt() {
     return [
@@ -21,8 +21,9 @@ function buildDeciderSystemPrompt() {
         'Decide whether the goal is now met (STOP) or another iteration is needed (CONTINUE).',
         'Be strict: only STOP when the goal is genuinely satisfied by the evidence in the history.',
         'A step CLAIMING success (e.g. printing "VERIFICATION: PASS") is NOT proof on its own — weigh it against the SPEC. If the spec describes work the history does not yet evidence as done, CONTINUE even if a step reported success.',
+        'BLOCKED is a THIRD option, distinct from continue/stop. Choose "blocked" when the loop is stuck on a decision only a HUMAN can make and further iterations cannot make progress — e.g. the latest step printed a line starting `LOOP_BLOCKED:`, OR a step repeatedly asks the human the same question / reports it will not proceed without a decision, OR the history shows several iterations with no new progress toward the goal. Do NOT pick "continue" in those cases — it just burns iterations. Put the blocking question in `reasoning`.',
         'Respond with ONLY a single-line JSON object — no prose, no markdown, no code fences:',
-        '{"action":"continue"|"stop","reasoning":"<one short sentence>"}',
+        '{"action":"continue"|"stop"|"blocked","reasoning":"<one short sentence>"}',
     ].join('\n');
 }
 function buildDeciderUserPrompt(input) {
@@ -52,9 +53,10 @@ function parseDeciderDecision(raw) {
             try {
                 const obj = JSON.parse(matches[i]);
                 const action = typeof obj.action === 'string' ? obj.action.toLowerCase().trim() : '';
-                if (action === 'stop' || action === 'continue') {
+                if (action === 'stop' || action === 'continue' || action === 'blocked') {
                     return {
                         continue: action === 'continue',
+                        blocked: action === 'blocked',
                         reasoning: typeof obj.reasoning === 'string' ? obj.reasoning : '',
                         parsed: true,
                     };
@@ -65,5 +67,5 @@ function parseDeciderDecision(raw) {
             }
         }
     }
-    return { continue: true, reasoning: '(could not parse decision; continuing)', parsed: false };
+    return { continue: true, blocked: false, reasoning: '(could not parse decision; continuing)', parsed: false };
 }

package/server/dist/loop-executors.js

@@ -13,9 +13,11 @@ exports.createLoopExecutors = createLoopExecutors;
  * fake executors in `loop-run-manager.test.ts`.
  */
 const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
 const tree_kill_1 = __importDefault(require("tree-kill"));
 const providers_1 = require("./providers");
 const workspace_manager_1 = require("./workspace-manager");
+const claude_trust_1 = require("./claude-trust");
 const spawn_lifecycle_1 = require("./spawn-lifecycle");
 const result_event_1 = require("./result-event");
 const loop_decider_1 = require("./loop-decider");
@@ -118,6 +120,24 @@ function aiStepExtraArgs(adapter, cwd, repoDir) {
 function createLoopExecutors(opts = {}) {
     const resolveEnv = () => typeof opts.env === 'function' ? opts.env() : opts.env ?? process.env;
     return {
+        // Cheap working-tree fingerprint for the engine's non-convergence guard:
+        // HEAD sha + the porcelain dirty set, hashed. Two identical fingerprints
+        // across consecutive Decider 'continue' verdicts ⇒ the loop changed nothing
+        // ⇒ abort `stalled`. Synchronous + best-effort: any git failure (no repo,
+        // detached, etc.) returns null so the guard simply stays off. Never throws.
+        repoStateHash(dir) {
+            try {
+                const opt = { cwd: dir, encoding: 'utf-8', timeout: 5_000, stdio: ['ignore', 'pipe', 'ignore'] };
+                const head = (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], opt).trim();
+                // `-z` NUL-delimited + include untracked so a brand-new file counts as
+                // a change; stable ordering makes the hash deterministic per tree state.
+                const porcelain = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-z', '--untracked-files=all'], opt);
+                return (0, node_crypto_1.createHash)('sha256').update(head).update('\0').update(porcelain).digest('hex');
+            }
+            catch {
+                return null;
+            }
+        },
         async runAiStep({ prompt, sessionId, provider, model, effort, cwd, repoDir, onLine, onRawLine, onSpawn, aiStepTimeoutMs }) {
             const adapter = (0, providers_1.getAdapter)(provider);
             // First iteration spawns headless (rail-job); subsequent iterations resume
@@ -133,9 +153,16 @@ function createLoopExecutors(opts = {}) {
             if (repoDir) {
                 try {
                     (0, workspace_manager_1.ensureFrameworkAgents)(cwd, adapter.projectDirName);
+                    (0, workspace_manager_1.ensureFrameworkCommandSubtrees)(cwd, adapter.projectDirName);
                 }
                 catch { /* best-effort */ }
             }
+            // Pre-trust the spawn dir so headless claude honours the overlaid
+            // `.claude/settings.json` permissions.allow (else "workspace not trusted").
+            try {
+                (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [cwd, repoDir]);
+            }
+            catch { /* best-effort */ }
             let text = '';
             // The adapter parses provider failures (codex `turn.failed`, etc.) into a
             // structured `error` event on the stdout stream — capture its message so we
@@ -243,9 +270,16 @@ function createLoopExecutors(opts = {}) {
             if (repoDir) {
                 try {
                     (0, workspace_manager_1.ensureFrameworkAgents)(cwd, adapter.projectDirName);
+                    (0, workspace_manager_1.ensureFrameworkCommandSubtrees)(cwd, adapter.projectDirName);
                 }
                 catch { /* best-effort */ }
             }
+            // Pre-trust the spawn dir so headless claude honours the overlaid
+            // `.claude/settings.json` permissions.allow (else "workspace not trusted").
+            try {
+                (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [cwd, repoDir]);
+            }
+            catch { /* best-effort */ }
             const args = adapter.buildArgs('chat-stream', {
                 // chat-stream feeds the prompt over stdin per-turn, so the argv `prompt`
                 // is unused — pass empty to satisfy the shared SpawnOptions shape.

package/server/dist/loop-run-manager.js

@@ -309,6 +309,15 @@ class LoopRunManager {
         // Consecutive AI steps that hard-failed with no output (provider down /
         // out of quota / crashing). Reset on any step that runs or produces output.
         let consecutiveAiFailures = 0;
+        // Non-convergence guard: the working-tree fingerprint at the last Decider
+        // verdict, and how many consecutive 'continue' verdicts have left it
+        // UNCHANGED. Two zero-change iterations in a row ⇒ the loop is spinning
+        // without progress (verify→fix→verify producing an identical tree) → abort
+        // `stalled` instead of burning iterations/cost. Disabled when the executor
+        // provides no `repoStateHash` or it can't read the tree.
+        let lastRepoHash = null;
+        let consecutiveNoProgress = 0;
+        const NO_PROGRESS_LIMIT = 2;
         // True for the step that runs immediately after a Decider 'continue' — that
         // step must see the cross-iteration history (the verdict it acts on). Mid-body
         // RESUMED steps already carry prior context in their session, so re-appending
@@ -660,10 +669,11 @@ class LoopRunManager {
                         // is truly down the Decider also fails → parsed=false → no reset.)
                         if (dec.parsed)
                             consecutiveAiFailures = 0;
+                        const verdictWord = dec.blocked ? 'blocked' : dec.continue ? 'continue' : 'stop';
                         // BUG-03: a Decider that couldn't parse a verdict (dec.parsed === false)
                         // is a failed AI invocation — record it as such, not as success.
                         record(`loop:${runId}:decider`, { ...dec, failed: !dec.parsed }, deciderStart);
-                        logLine(`Decision: ${dec.continue ? 'continue' : 'stop'} — ${dec.reasoning}`);
+                        logLine(`Decision: ${verdictWord} — ${dec.reasoning}`);
                         // The verdict line above is the decider step's last output. `decision`
                         // is the route actually taken (an unparseable verdict defaults to
                         // continue AND flags the step failed — mirrors record()'s status).
@@ -672,7 +682,7 @@ class LoopRunManager {
                             durationMs: dec.durationMs,
                             decision: dec.continue ? 'continue' : 'stop',
                         });
-                        history.push(`Decider: ${dec.continue ? 'continue' : 'stop'} — ${dec.reasoning}`);
+                        history.push(`Decider: ${verdictWord} — ${dec.reasoning}`);
                         (0, loop_runs_store_1.updateLoopRunCounters)(this.db, runId, {
                             iterationCount: iteration,
                             totalCostUsd: totalCost,
@@ -696,6 +706,40 @@ class LoopRunManager {
                         const branchTarget = (b) => out.find((e) => e.branch === b)?.target;
                         const ends = succs.filter((n) => n.type === 'end');
                         const conts = succs.filter((n) => n.type !== 'end');
+                        // BLOCKED: the loop is stuck on a human decision — halt now with a
+                        // dedicated outcome (NOT success) and surface the question. This is
+                        // the fix for the verify→fix cycle spinning on an unanswered scope
+                        // question the loop can't resolve on its own.
+                        if (dec.blocked) {
+                            logLine(`\n■ Loop blocked — needs a human decision: ${dec.reasoning}`, 'stderr');
+                            outcome = 'blocked';
+                            settled = true;
+                            break;
+                        }
+                        // Non-convergence guard: if two consecutive 'continue' iterations
+                        // leave the working tree byte-identical, the loop isn't progressing
+                        // (e.g. verify keeps passing a baseline while the feature is never
+                        // written) — abort `stalled` rather than cycle to the cap.
+                        if (dec.continue && this.executors.repoStateHash) {
+                            const dir = req.repoDir ?? req.cwd;
+                            const hash = this.executors.repoStateHash(dir);
+                            // null = couldn't read the tree → skip (never let null match null).
+                            if (hash !== null) {
+                                if (hash === lastRepoHash) {
+                                    consecutiveNoProgress += 1;
+                                    if (consecutiveNoProgress >= NO_PROGRESS_LIMIT) {
+                                        logLine(`\n■ Loop stalled — ${consecutiveNoProgress + 1} iterations changed nothing in the working tree; stopping instead of cycling.`, 'stderr');
+                                        outcome = 'stalled';
+                                        settled = true;
+                                        break;
+                                    }
+                                }
+                                else {
+                                    consecutiveNoProgress = 0;
+                                }
+                                lastRepoHash = hash;
+                            }
+                        }
                         if (dec.continue) {
                             const target = branchTarget('continue') ?? conts[0]?.id;
                             if (target) {
@@ -759,7 +803,12 @@ class LoopRunManager {
         // Settle the backing job so the Jobs list + JobDetail reflect the final
         // status, and emit job.finalized so an open JobDetail re-fetches + stops the
         // live stream (mirrors QueueManager).
-        const jobStatus = outcome === 'success' ? 'completed' : outcome === 'stopped' ? 'canceled' : 'failed';
+        // `blocked`/`stalled` are controlled halts (not done, not a hard crash) →
+        // surface as `canceled`, like a user stop, so tickets revert to todo rather
+        // than being marked done/on_review AND the run is never counted as success.
+        const jobStatus = outcome === 'success' ? 'completed'
+            : outcome === 'stopped' || outcome === 'blocked' || outcome === 'stalled' ? 'canceled'
+                : 'failed';
         // `≥` when any cost-bearing step ended unpriced (timeout/crash) — the figure
         // is a lower bound, not exact.
         logLine(`\n■ Loop finished: ${outcome} — ${iteration} iteration${iteration === 1 ? '' : 's'}, ${costUncertain ? '≥ ' : ''}$${totalCost.toFixed(4)}`);

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

@@ -16,6 +16,7 @@ const loops_1 = require("./loops");
 const code_1 = require("./code");
 const setup_1 = require("./setup");
 const analytics_1 = require("./analytics");
+const git_1 = require("./git");
 /**
  * The full MCP tool catalog. Domain-facade tools each expose an `action` enum
  * and call the app's REST API over loopback (see apiCall). Meta tools receive a
@@ -39,6 +40,7 @@ function buildToolSpecs() {
     specs.push(...(0, code_1.codeTools)());
     specs.push(...(0, setup_1.setupTools)());
     specs.push(...(0, analytics_1.analyticsTools)());
+    specs.push(...(0, git_1.gitTools)());
     // Meta last (needs the full list for search/describe)
     specs.push(...(0, meta_1.metaTools)(() => specs));
     return specs;

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitTools = gitTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+const git_diagnostics_1 = require("../../git-diagnostics");
+/**
+ * Read-only git / GitHub (gh) diagnostics for a project, run through the app's
+ * OWN bundled git/gh against the repo. This is the sanctioned MCP path for the
+ * operator agent to inspect version-control state — it does NOT need (and should
+ * not use) a raw shell for this. Every action is a FIXED, read-only command; the
+ * caller only names an action, never arguments. Repo MUTATIONS (push, pr create,
+ * commit) are intentionally NOT here — those belong to the ask-first PR flow
+ * (specrails_rails PR decisions), which is auditable and confirmation-gated.
+ */
+function gitTools() {
+    const help = (0, git_diagnostics_1.gitDiagnosticHelp)();
+    const actionLines = git_diagnostics_1.GIT_DIAGNOSTIC_ACTIONS.map((a) => `${a} (${help[a]})`).join('; ');
+    return [
+        {
+            name: 'specrails_git',
+            title: 'Git & GitHub diagnostics',
+            description: "READ-ONLY git/GitHub diagnostics for a project, via the app's bundled git/gh — use this " +
+                "(not a raw shell) to answer questions like \"is this repo connected to GitHub?\", \"what's the " +
+                'remote?\", \"is gh authenticated?\", \"what changed?\", or to inspect PRs. Runs against the ' +
+                "project's real repo. All actions are read-only and never prompt. " +
+                `Actions: ${actionLines}. ` +
+                'These are NOT for mutating the repo — pushing / creating PRs / committing go through the ' +
+                'ask-first PR flow (specrails_rails PR decisions), never here.',
+            hintTier: 'read',
+            tier: 'read',
+            inputSchema: {
+                action: zod_1.z
+                    .enum(git_diagnostics_1.GIT_DIAGNOSTIC_ACTIONS)
+                    .describe('Which read-only diagnostic to run'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+            },
+            async handler(ctx, args) {
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                const action = args.action;
+                if (!(0, git_diagnostics_1.isGitDiagnosticAction)(action)) {
+                    throw new Error(`Unknown action "${action}". Allowed: ${git_diagnostics_1.GIT_DIAGNOSTIC_ACTIONS.join(', ')}.`);
+                }
+                const qs = new URLSearchParams({ action });
+                const r = (await (0, types_1.apiCall)(ctx, 'GET', `${base}/git/diagnostic?${qs.toString()}`));
+                // A non-zero exit is a NORMAL, informative outcome (e.g. `gh repo view`
+                // when the repo has no GitHub remote) — surface it plainly so the agent
+                // reports the real state instead of treating it as an error.
+                return {
+                    ...r,
+                    hint: r.ok === false
+                        ? 'The command exited non-zero — this is often meaningful (e.g. no GitHub remote, or gh not authenticated). Read stderr/stdout and report the real state to the user; do not treat it as a tool failure.'
+                        : undefined,
+                };
+            },
+        },
+    ];
+}

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

@@ -208,10 +208,33 @@ function railsTools() {
                             body.reasoning_effort = defaults.reasoningEffort;
                         }
                         const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/${railIndex}/launch`, body);
+                        const railLabel = `Rail ${railIndex + 1}`;
+                        // Isolation status governs whether a PR-decision card EXISTS. When
+                        // the router reports `isolationUnavailable`, the run fell back to the
+                        // shared working tree: NO git worktree, NO PR delivery row, and so
+                        // NO implementation/PR card will EVER appear (not in this chat, not
+                        // in the rail header). The agent MUST NOT promise one — it must tell
+                        // the user the run writes changes DIRECTLY to their files and why.
+                        const isoReason = typeof r.isolationUnavailable === 'string' ? r.isolationUnavailable : null;
+                        if (isoReason) {
+                            const why = isoReason === 'no-git'
+                                ? 'the project folder is NOT a git repository'
+                                : isoReason === 'no-commits'
+                                    ? 'the git repository has NO commits yet (an unborn HEAD cannot be branched)'
+                                    : `worktree isolation failed${typeof r.isolationUnavailableDetail === 'string' ? `: ${r.isolationUnavailableDetail}` : ''}`;
+                            const fix = isoReason === 'error'
+                                ? 'This is unexpected — report the detail to the user.'
+                                : 'To get the PR flow, the user should `git init` the folder and make at least one commit (a GitHub remote is NOT required — the review flow then offers "Integrate locally" to accept without GitHub), then relaunch.';
+                            return {
+                                ...r,
+                                railLabel,
+                                hint: `Launch accepted (202) on ${railLabel}, but WORKTREE ISOLATION IS UNAVAILABLE because ${why}. The run proceeds on the SHARED working tree and writes changes DIRECTLY into the user's files — there is NO PR-decision/implementation card and NO branch. Do NOT tell the user to look for a PR card; tell them the run writes to their files in place, and explain why. ${fix} When it finishes, the spec parks at on_review — the user accepts it by moving it to Done on the board (the changes are already in their files) or reverts the spec's status (which does NOT undo the file changes).`,
+                            };
+                        }
                         return {
                             ...r,
-                            railLabel: `Rail ${railIndex + 1}`,
-                            hint: `Launch accepted (202) on railIndex ${railIndex} — tell the user it runs on "Rail ${railIndex + 1}" (UI labels are 1-based). Use specrails_watch with the returned jobId/jobIds (or loopRunIds for loop mode) to await completion. Live output streams over the job WS. Rails run for minutes; pass untilMs up to 600000 and re-watch on timeout.`,
+                            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.`,
                         };
                     }
                     case 'launch_all': {

package/server/dist/project-registry.js

@@ -727,7 +727,12 @@ class ProjectRegistry {
             const ticketIds = meta.ticketIds;
             if (ticketIds.length === 0)
                 return;
-            const status = outcome === 'success' ? 'completed' : outcome === 'stopped' ? 'canceled' : 'failed';
+            // `blocked`/`stalled` (Decider-flagged human blocker / non-convergence
+            // abort) are controlled halts: treat like a user stop → `canceled`, so
+            // tickets revert to todo (never done/on_review) and no PR delivery fires.
+            const status = outcome === 'success' ? 'completed'
+                : outcome === 'stopped' || outcome === 'blocked' || outcome === 'stalled' ? 'canceled'
+                    : 'failed';
             // Ask-first PR delivery parks a completed run's tickets at on_review (the
             // user decides done vs discard via the PR decision flow / a manual move).
             // Explicit opts (the isolated-rail launch passes its launch-captured

package/server/dist/project-router-git.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerGitRoutes = registerGitRoutes;
 const project_git_1 = require("./project-git");
+const git_diagnostics_1 = require("./git-diagnostics");
 // ─── Git domain routes (/api/projects/:projectId/git) ─────────────────────────
 //
 // Backs the Agent-Mode git bar: current branch + last commit + local branches,
@@ -18,6 +19,24 @@ function registerGitRoutes(deps) {
             res.status(500).json({ error: 'Failed to read git info' });
         }
     });
+    // READ-ONLY git/gh diagnostics (backs the specrails_git MCP tool). A fixed
+    // allowlist of read-only commands — the query only names an action, never
+    // arguments. Git runs against project.path (the real repo; the workspace never
+    // holds code under relocation).
+    router.get('/:projectId/git/diagnostic', async (req, res) => {
+        const action = String(req.query.action ?? '');
+        if (!(0, git_diagnostics_1.isGitDiagnosticAction)(action)) {
+            res.status(400).json({ error: 'invalid_action', allowed: git_diagnostics_1.GIT_DIAGNOSTIC_ACTIONS });
+            return;
+        }
+        try {
+            res.json(await (0, git_diagnostics_1.runGitDiagnostic)(action, ctx(req).project.path));
+        }
+        catch (err) {
+            console.error('[project-git] diagnostic failed:', err);
+            res.status(500).json({ error: 'diagnostic_failed', detail: err instanceof Error ? err.message : String(err) });
+        }
+    });
     router.post('/:projectId/git/checkout', async (req, res) => {
         const body = (req.body ?? {});
         const branch = typeof body.branch === 'string' ? body.branch.trim() : '';

package/server/dist/queue-manager.js

@@ -31,6 +31,7 @@ const attachment_manager_1 = require("./attachment-manager");
 const ticket_store_1 = require("./ticket-store");
 const binary_probe_1 = require("./binary-probe");
 const workspace_manager_1 = require("./workspace-manager");
+const claude_trust_1 = require("./claude-trust");
 const workspace_resolution_1 = require("./workspace-resolution");
 const framework_manager_1 = require("./framework-manager");
 const openspec_shim_1 = require("./openspec-shim");
@@ -1427,11 +1428,24 @@ class QueueManager {
         if (execution.relocated) {
             try {
                 (0, workspace_manager_1.ensureFrameworkAgents)(execution.cwd, adapter.projectDirName);
+                // AND the dir-linked subtrees (commands/skills/rules): a broken Windows
+                // `current` junction leaves the workspace with no `/specrails:*` commands
+                // → the CLI reports "Unknown command: /specrails:implement".
+                (0, workspace_manager_1.ensureFrameworkCommandSubtrees)(execution.cwd, adapter.projectDirName);
             }
             catch {
                 /* best-effort — never block a rail spawn on the repair */
             }
         }
+        // Pre-trust the spawn dir(s) so headless claude honours the overlaid
+        // `.claude/settings.json` permissions.allow (else it silently drops them:
+        // "this workspace has not been trusted"). Once per unique dir, claude-only.
+        try {
+            (0, claude_trust_1.ensureClaudeTrusted)(adapter.id, [execution.cwd, execution.repoDir]);
+        }
+        catch {
+            /* best-effort */
+        }
         job.status = 'running';
         job.startedAt = new Date().toISOString();
         job.queuePosition = null;