specrails-desktop 2.64.1 → 2.65.0

package/server/dist/modules/delivery/runtime/flow-worktree-return.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowReturnRejectedError = void 0;
+exports.returnFlowWorktree = returnFlowWorktree;
+exports.announceReturnedDelivery = announceReturnedDelivery;
+const agent_chat_registry_1 = require("../../missions/runtime/agent-chat-registry");
+const flow_review_outcome_1 = require("./flow-review-outcome");
+const rail_pr_store_1 = require("./rail-pr-store");
+const TERMINAL_DECISIONS = new Set(['merged', 'completed', 'discarded', 'superseded']);
+/** The delivery cannot give its worktree back now (HTTP 409). */
+class FlowReturnRejectedError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FlowReturnRejectedError';
+    }
+}
+exports.FlowReturnRejectedError = FlowReturnRejectedError;
+/**
+ * Transfer the adopted worktree back. `commit` runs INSIDE the transaction
+ * (it saves the Flow's state); throwing rolls back the ledger and the delivery
+ * too. Idempotent: a delivery already `returned_to_flow` returns its snapshot
+ * without calling `commit` again.
+ */
+function returnFlowWorktree(db, input, commit) {
+    return db.transaction(() => {
+        const row = (0, rail_pr_store_1.getPrDelivery)(db, input.deliveryId);
+        if (!row || row.loop_id !== flow_review_outcome_1.FLOW_SPEC_DELIVERY_LOOP_ID)
+            throw new FlowReturnRejectedError('flow_return_not_found', 'This delivery is not a Flow → Spec run');
+        if (row.decision === 'discarded' && row.status_code === 'returned_to_flow')
+            return (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+        if (row.decision !== 'implementation_failed') {
+            throw new FlowReturnRejectedError('flow_return_not_allowed', 'Only a Flow → Spec run that stopped before delivery can go back to its Flow');
+        }
+        if (row.operation_token || row.operation)
+            throw new FlowReturnRejectedError('flow_return_busy', 'The delivery is busy; try again when its current action finishes');
+        const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+        if (!snap.branches.some((unit) => unit.worktreePath === input.worktreePath)) {
+            throw new FlowReturnRejectedError('flow_return_worktree_mismatch', 'The delivery did not adopt this Flow worktree');
+        }
+        const runIds = new Set(snap.runIds);
+        const ledger = db.prepare('SELECT id, run_id FROM rail_worktrees WHERE worktree_path = ?').all(input.worktreePath)
+            .filter((entry) => entry.run_id === null || runIds.has(entry.run_id));
+        for (const entry of ledger)
+            db.prepare('DELETE FROM rail_worktrees WHERE id = ?').run(entry.id);
+        const released = new Set(ledger.map((entry) => entry.id));
+        // A Flow in a non-primary repository ran as a one-repository group: its
+        // child row closes with the parent (both before Flow commits), so no
+        // later group projection can reopen or re-settle the returned delivery.
+        const children = db.prepare('SELECT * FROM rail_pr_deliveries WHERE parent_delivery_id = ? ORDER BY rowid').all(row.id);
+        if (children.length > 1)
+            throw new FlowReturnRejectedError('flow_return_not_allowed', 'This delivery spans several repositories; a Flow worktree belongs to one');
+        if (children.some((child) => child.operation_token || child.operation))
+            throw new FlowReturnRejectedError('flow_return_busy', 'The delivery is busy; try again when its current action finishes');
+        if (!(0, rail_pr_store_1.transitionDecision)(db, row.id, 'implementation_failed', 'discarded', {
+            statusCode: 'returned_to_flow',
+            statusDetail: input.detail,
+            worktreeIds: snap.worktreeIds.filter((id) => !released.has(id)),
+        }))
+            throw new FlowReturnRejectedError('flow_return_busy', 'The delivery changed while returning its worktree');
+        for (const child of children) {
+            if (TERMINAL_DECISIONS.has(child.decision))
+                continue;
+            if (!(0, rail_pr_store_1.transitionDecision)(db, child.id, child.decision, 'discarded', {
+                statusCode: 'returned_to_flow',
+                statusDetail: input.detail,
+                worktreeIds: (0, rail_pr_store_1.toPrDeliverySnapshot)(child).worktreeIds.filter((id) => !released.has(id)),
+            }))
+                throw new FlowReturnRejectedError('flow_return_busy', 'The delivery changed while returning its worktree');
+        }
+        commit();
+        return (0, rail_pr_store_1.toPrDeliverySnapshot)((0, rail_pr_store_1.getPrDelivery)(db, row.id));
+    })();
+}
+/** Re-broadcast a closed delivery to the rail strip and its mission card. Never throws. */
+function announceReturnedDelivery(projectId, snap, broadcast) {
+    try {
+        broadcast((0, rail_pr_store_1.toRailPrStateMessage)(projectId, snap));
+    }
+    catch { /* hydration recovers */ }
+    try {
+        if (snap.originConversationId)
+            (0, agent_chat_registry_1.getAgentChatManager)()?.updatePrDecisionCard(snap.originConversationId, (0, rail_pr_store_1.toPrDecisionCardEnvelope)(projectId, snap));
+    }
+    catch { /* the card refreshes on its next hydration */ }
+}

package/server/dist/modules/delivery/runtime/isolated-worktree.js

@@ -0,0 +1,380 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepositoryHasNoCommitsError = void 0;
+exports.assertRepositoryHasCommits = assertRepositoryHasCommits;
+exports.ticketNamingInput = ticketNamingInput;
+exports.readHeadSha = readHeadSha;
+exports.isolatedWorktreesRoot = isolatedWorktreesRoot;
+exports.resolveOverlaySources = resolveOverlaySources;
+exports.materializeIsolatedWorktree = materializeIsolatedWorktree;
+exports.isolatedRepositoryTarget = isolatedRepositoryTarget;
+exports.prepareIsolatedWorktree = prepareIsolatedWorktree;
+/**
+ * Isolated worktree preparation — the single machinery that turns a ticket into
+ * a dedicated, run-ready checkout. Shared by the isolated rail launch (which
+ * owns batching, PR continuation, delivery rows and the rail ledger) and any
+ * other consumer that needs "one fresh worktree for this ticket" (Flow).
+ *
+ * `materializeIsolatedWorktree` is the lock-free core: create/reuse the mount,
+ * verify its HEAD, apply the per-run framework overlay, link warm
+ * `node_modules` and freeze the Code-Explorer provenance snapshot. The caller
+ * MUST hold `withRepoLock(repoDir)`. A verification failure removes only the
+ * resources this call created (ownership-aware rollback) and rethrows.
+ *
+ * `prepareIsolatedWorktree` is the self-contained public entry: it takes the
+ * repository lock, refreshes remote-tracking refs, resolves the base ref and
+ * conventional branch name exactly as a rail launch does, then materializes.
+ * It records no rail ledger row; the caller owns the returned checkout.
+ */
+const path = __importStar(require("path"));
+const artifact_registry_1 = require("../../../artifact-registry");
+const ids_1 = require("../../../ids");
+const db_1 = require("../../../db");
+const jira_db_1 = require("../../../jira/jira-db");
+const providers_1 = require("../../../providers");
+const feature_flags_1 = require("../../../feature-flags");
+const repo_lock_1 = require("../../../repo-lock");
+const project_repositories_1 = require("../../../project-repositories");
+const workspace_resolution_1 = require("../../../workspace-resolution");
+const integration_branch_1 = require("../../../integration-branch");
+const worktree_manager_1 = require("../../../worktree-manager");
+const worktree_overlay_1 = require("../../../worktree-overlay");
+const worktree_node_modules_1 = require("../../../worktree-node-modules");
+const file_provenance_1 = require("../../code/runtime/file-provenance");
+const pr_naming_1 = require("./pr-naming");
+const COMMIT_SHA_RE = /^[0-9a-f]{40,64}$/i;
+/** The repository has an unborn HEAD (no commits yet), so no isolated worktree
+ *  can be branched from it. Raised before anything is created. */
+class RepositoryHasNoCommitsError extends Error {
+    repoDir;
+    code = 'repository_has_no_commits';
+    constructor(repoDir) {
+        super('This repository has no commits yet. Make an initial commit so Specrails can create an isolated worktree.');
+        this.repoDir = repoDir;
+        this.name = 'RepositoryHasNoCommitsError';
+    }
+}
+exports.RepositoryHasNoCommitsError = RepositoryHasNoCommitsError;
+/**
+ * Fail closed with `RepositoryHasNoCommitsError` when `repoDir` is a Git
+ * repository with an unborn HEAD, no local branch at all, and a `baseRef` that
+ * does not resolve to a commit. Any other Git failure (not a repository, a
+ * missing branch next to real commits) is left to the regular worktree path so
+ * its own error stays visible. Read-only: nothing is created.
+ */
+async function assertRepositoryHasCommits(git, repoDir, baseRef) {
+    const base = await git.run(['rev-parse', '--verify', '--quiet', `${baseRef}^{commit}`], repoDir);
+    if (base.code === 0)
+        return;
+    const head = await git.run(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], repoDir);
+    if (head.code === 0)
+        return;
+    // An unborn HEAD is still a symbolic ref; a non-repository is not.
+    const symbolic = await git.run(['symbolic-ref', '-q', 'HEAD'], repoDir);
+    if (symbolic.code !== 0)
+        return;
+    const anyBranch = await git.run(['for-each-ref', '--count=1', '--format=%(refname)', 'refs/heads'], repoDir);
+    if (anyBranch.code !== 0 || anyBranch.stdout.trim() !== '')
+        return;
+    throw new RepositoryHasNoCommitsError(repoDir);
+}
+/**
+ * Ticket data for the conventional branch name (pr-naming): title/labels from
+ * the ticket-spec reader, the Jira key resolved with the authoritative
+ * `jira_links` row prevailing over the ticket's own `jira_key` field (JIRA
+ * ALWAYS PREVAILS). Fully failure-tolerant — a missing store/link degrades to
+ * the bare local ticket id.
+ */
+function ticketNamingInput(ctx, ticketId) {
+    let spec;
+    try {
+        spec = ctx.getTicketSpec(ticketId);
+    }
+    catch {
+        /* tolerated */
+    }
+    let jiraKey = spec?.jira_key ?? null;
+    try {
+        const link = (0, jira_db_1.getLinkByLocalId)(ctx.db, ticketId);
+        if (link && !link.tombstoned && link.jiraKey)
+            jiraKey = link.jiraKey;
+    }
+    catch {
+        /* tolerated */
+    }
+    return { ticketId, title: spec?.title ?? null, labels: spec?.labels ?? null, jiraKey };
+}
+async function readHeadSha(git, cwd) {
+    try {
+        const result = await git.run(['rev-parse', '--verify', 'HEAD'], cwd);
+        const sha = result.code === 0 ? result.stdout.trim() : '';
+        return COMMIT_SHA_RE.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `~/.specrails/projects/<slug>/worktrees[/<repositoryId>]` — per-run mounts
+ *  live beneath `<root>/<runId>`. */
+function isolatedWorktreesRoot(slug, repositoryId) {
+    return path.join((0, artifact_registry_1.resolveHome)(), '.specrails', 'projects', slug, 'worktrees', ...(repositoryId ? [repositoryId] : []));
+}
+/**
+ * Effective artifact root for the per-worktree overlay: a RELOCATED project's
+ * framework surface (slash commands, sr-* agents, skills, rules, .mcp.json,
+ * instruction file) lives in the WORKSPACE, not the repo — and `git worktree
+ * add` materializes only TRACKED files, so without the overlay a relocated
+ * worktree spawn has no `/specrails:*` commands at all. Legacy projects
+ * overlay their repo's own untracked on-disk entries instead. A resolution
+ * failure degrades to the legacy (repo) source; an unknown provider degrades
+ * to claude-shaped defaults.
+ */
+function resolveOverlaySources(input, resolveExecution = workspace_resolution_1.resolveProjectExecution) {
+    let sourceRoot = input.baseRepo;
+    let fallbackSourceRoots;
+    try {
+        const exec = resolveExecution({ slug: input.slug, path: input.baseRepo });
+        if (exec.relocated && exec.workspaceDir) {
+            sourceRoot = exec.workspaceDir;
+            // The repo as FALLBACK root: repo-resident untracked carve-outs
+            // (OpenSpec's `/opsx:*` commands, `openspec-*` skills, user extras)
+            // are absent from both the checkout (untracked) and the workspace
+            // (the framework ships only `specrails/`), so without this the claude
+            // CLI reports `Unknown command: /opsx:ff` inside isolated rails.
+            fallbackSourceRoots = [input.baseRepo];
+        }
+    }
+    catch { /* legacy fallback */ }
+    let providerDir = '.claude';
+    let instructionsFilename = 'CLAUDE.md';
+    try {
+        const adapter = (0, providers_1.getAdapter)(input.provider);
+        providerDir = adapter.projectDirName;
+        instructionsFilename = adapter.instructionsFilename;
+    }
+    catch { /* unknown provider — claude-shaped defaults */ }
+    return { sourceRoot, fallbackSourceRoots, providerDir, instructionsFilename };
+}
+/**
+ * Create (or resume) the worktree, verify it, then apply the overlay, warm
+ * links and provenance snapshot. The caller holds the repository lock.
+ */
+async function materializeIsolatedWorktree(input, io = {}) {
+    const git = io.git ?? worktree_manager_1.defaultGitRunner;
+    const create = io.create ?? worktree_manager_1.createWorktree;
+    const remove = io.remove ?? worktree_manager_1.removeWorktree;
+    const overlay = io.overlay ?? worktree_overlay_1.applyWorktreeOverlay;
+    const handle = await create(git, {
+        repoDir: input.repoDir,
+        worktreesRoot: input.worktreesRoot,
+        slug: input.slug,
+        ticketId: input.ticketId,
+        baseRef: input.baseRef,
+        branch: input.branch,
+        refreshFromBaseRef: input.refreshFromBaseRef,
+        fresh: input.fresh,
+        reuseBranchWorktree: input.reuseBranchWorktree,
+    });
+    const worktreeOwnership = handle.worktreeCreated === false ? 'preexisting' : 'created';
+    let branchOwnership = input.branchOwnership;
+    if (!input.pinBranchOwnership && (handle.branch !== input.branch || handle.branchCreated === false)) {
+        branchOwnership = 'preexisting';
+    }
+    let initialSha;
+    try {
+        initialSha = input.verifyHead
+            ? await input.verifyHead(handle, git)
+            : await readHeadSha(git, handle.worktreePath);
+    }
+    catch (err) {
+        // Only unmount/delete resources this call actually created.
+        if (worktreeOwnership === 'created') {
+            await remove(git, {
+                repoDir: input.repoDir,
+                worktreePath: handle.worktreePath,
+                branch: handle.branch,
+                deleteBranch: branchOwnership === 'created',
+            }).catch(() => { });
+        }
+        throw err;
+    }
+    // Per-run overlay: merge-link the framework surface the checkout didn't
+    // bring into the worktree (idempotent; resume-safe via its manifest).
+    let overlayExcludes = [];
+    let overlayCleanupEvidence = [];
+    try {
+        const res = overlay({
+            worktreePath: handle.worktreePath,
+            sourceRoot: input.overlay.sourceRoot,
+            fallbackSourceRoots: input.overlay.fallbackSourceRoots,
+            providerDir: input.overlay.providerDir,
+            instructionsFilename: input.overlay.instructionsFilename,
+        });
+        overlayExcludes = res.createdPaths;
+        overlayCleanupEvidence = res.cleanupEvidence ?? [];
+        if (res.warnings.length > 0)
+            input.onDegraded(res.warnings);
+    }
+    catch (err) {
+        // applyWorktreeOverlay never throws; this guards injected test doubles
+        // and future edits — the spawn proceeds regardless.
+        input.onDegraded([err instanceof Error ? err.message : String(err)]);
+    }
+    // Warm-dependency reuse: link the base checkout's node_modules trees into
+    // the fresh worktree (best-effort; a failure just leaves the run on the
+    // legacy cold start). Linked paths join the overlay exclusion list so they
+    // inherit the commit-time guarantees.
+    let warmLinkEvidence = [];
+    try {
+        const nm = (io.linkNodeModules ?? worktree_node_modules_1.linkNodeModulesIntoWorktree)(input.repoDir, handle.worktreePath);
+        // `authenticated` (not `linked`) is the authorized set: it also covers
+        // links a previous pass created, which a resumed launch would otherwise
+        // leave both un-excluded from the commit and unauthorized for release.
+        const authorized = nm.authenticated ?? nm.linked ?? [];
+        if (authorized.length > 0)
+            overlayExcludes = overlayExcludes.concat(authorized);
+        warmLinkEvidence = nm.evidence ?? [];
+        if (nm.warnings.length > 0)
+            input.onDegraded(nm.warnings);
+    }
+    catch (err) {
+        input.onDegraded([err instanceof Error ? err.message : String(err)]);
+    }
+    // Code-Explorer provenance: freeze the worktree's pre-run state (HEAD sha +
+    // the overlay's untracked set) so the settle diff attributes exactly the
+    // run's own writes. Best-effort — a snapshot failure only loses provenance.
+    let provenanceSnapshot = null;
+    if ((0, feature_flags_1.isCodeExplorerEnabled)()) {
+        try {
+            provenanceSnapshot = (io.snapshot ?? file_provenance_1.snapshotWorkingTree)(handle.worktreePath);
+        }
+        catch (err) {
+            console.warn(`[rail-isolated] provenance snapshot failed: ${err.message}`);
+        }
+    }
+    return {
+        handle,
+        worktreePath: handle.worktreePath,
+        branch: handle.branch,
+        initialSha,
+        overlayExcludes,
+        overlayCleanupEvidence,
+        warmLinkEvidence,
+        provenanceSnapshot,
+        branchOwnership,
+        worktreeOwnership,
+    };
+}
+/**
+ * The checkout a repository-scoped worktree is cut from. Absent/null or the
+ * primary id ⇒ the project root with the project's integration setting and
+ * the shared mount root (unchanged single-repository behaviour); a non-primary
+ * Git member ⇒ its own checkout, its own integration branch and the
+ * per-repository mount root (`isolatedWorktreesRoot(slug, repositoryId)`), as
+ * the multi-repository rail children use.
+ */
+function isolatedRepositoryTarget(project, repositoryId) {
+    const members = (0, project_repositories_1.getProjectRepositories)(project);
+    const primary = members.find((repo) => repo.isPrimary);
+    if (!repositoryId || repositoryId === primary?.id) {
+        return { repositoryId: null, path: project.path, primary: true, integrationBranch: primary?.integrationBranch ?? null, worktreesRoot: isolatedWorktreesRoot(project.slug) };
+    }
+    const member = members.find((repo) => repo.id === repositoryId);
+    if (!member)
+        throw new Error(`Unknown project repository: ${repositoryId}`);
+    if (member.kind !== 'git')
+        throw new Error(`Repository ${member.name} is context-only; isolated worktrees need a Git repository`);
+    return { repositoryId: member.id, path: member.path, primary: false, integrationBranch: member.integrationBranch, worktreesRoot: isolatedWorktreesRoot(project.slug, member.id) };
+}
+/**
+ * Prepare one fresh isolated worktree for a ticket under the repository lock:
+ * fetch, base ref resolution, branch planning, createWorktree, overlay, warm
+ * links and provenance snapshot. Rollback removes only what this call created.
+ * No rail ledger row is written; the caller owns the returned checkout and its
+ * release (using the returned ownership flags).
+ */
+async function prepareIsolatedWorktree(input, io = {}) {
+    const { ctx, ticketId } = input;
+    const git = io.git ?? worktree_manager_1.defaultGitRunner;
+    const target = isolatedRepositoryTarget(ctx.project, input.repositoryId);
+    const baseRepo = target.path;
+    const slug = ctx.project.slug;
+    const runId = input.runId ?? (0, ids_1.newId)();
+    const onDegraded = input.onDegraded ?? ((warnings) => {
+        console.error(`[isolated-worktree] worktree preparation degraded (ticket ${ticketId}): ${warnings.join('; ')}`);
+    });
+    // A non-primary member overlays the PROJECT's framework surface (the
+    // workspace when relocated), exactly like a multi-repository rail child.
+    const resolveExecution = io.resolveExecution ?? (target.primary ? undefined : () => (0, workspace_resolution_1.resolveProjectExecution)(ctx.project));
+    const overlaySources = resolveOverlaySources({ slug, baseRepo, provider: input.provider }, resolveExecution);
+    return (0, repo_lock_1.withRepoLock)(baseRepo, async () => {
+        const fetchResult = await (0, integration_branch_1.fetchOrigin)(git, baseRepo);
+        const integration = await (0, integration_branch_1.resolveIntegrationBranch)(git, {
+            repoDir: baseRepo,
+            explicit: input.baseRef ?? undefined,
+            projectSetting: target.primary ? target.integrationBranch ?? (0, db_1.getProjectSettings)(ctx.db).integrationBranch : target.integrationBranch ?? undefined,
+        });
+        const worktreeBaseRef = await (0, integration_branch_1.resolveWorktreeBaseRef)(git, { repoDir: baseRepo, integration, fetchOk: fetchResult.ok });
+        // Unborn HEAD: refuse before any branch, worktree or overlay exists.
+        await assertRepositoryHasCommits(git, baseRepo, worktreeBaseRef.baseRef);
+        if (worktreeBaseRef.warning)
+            onDegraded([worktreeBaseRef.warning]);
+        const frozen = await git.run(['rev-parse', '--verify', `${worktreeBaseRef.baseRef}^{commit}`], baseRepo);
+        const frozenSha = frozen.code === 0 ? frozen.stdout.trim() : '';
+        const baseSha = COMMIT_SHA_RE.test(frozenSha) ? frozenSha : null;
+        let branch = input.branch?.trim() || null;
+        if (!branch) {
+            const taken = await (0, worktree_manager_1.listLocalBranches)(git, baseRepo);
+            branch = (0, pr_naming_1.resolveCollisionFreeName)((0, pr_naming_1.ticketBranchName)(ticketNamingInput(ctx, ticketId)), {
+                taken: (name) => taken.has(name),
+                reserved: [integration.branch],
+            }) ?? (0, worktree_manager_1.worktreeBranch)(slug, ticketId);
+        }
+        const prepared = await materializeIsolatedWorktree({
+            repoDir: baseRepo,
+            worktreesRoot: path.join(target.worktreesRoot, runId),
+            slug,
+            ticketId,
+            baseRef: worktreeBaseRef.baseRef,
+            branch,
+            branchOwnership: 'created',
+            fresh: true,
+            overlay: overlaySources,
+            onDegraded,
+        }, io);
+        return { ...prepared, runId, baseRef: worktreeBaseRef.baseRef, baseSha, integrationBranch: integration.branch };
+    });
+}