specrails-desktop 2.64.2 → 2.65.0

package/server/dist/modules/delivery/runtime/local-stash.js

@@ -0,0 +1,423 @@
+"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.LOCAL_STASH_MESSAGE_PREFIX = void 0;
+exports.isSpecrailsManagedPath = isSpecrailsManagedPath;
+exports.localStashMessage = localStashMessage;
+exports.restoreBranchName = restoreBranchName;
+exports.failureText = failureText;
+exports.safeRun = safeRun;
+exports.nulList = nulList;
+exports.listUserDirtyPaths = listUserDirtyPaths;
+exports.changedPathsBetween = changedPathsBetween;
+exports.pathsOverlap = pathsOverlap;
+exports.listStashes = listStashes;
+exports.saveLocalChanges = saveLocalChanges;
+exports.stashPaths = stashPaths;
+exports.dropBySha = dropBySha;
+exports.resetPathsToHead = resetPathsToHead;
+exports.unmergedPaths = unmergedPaths;
+exports.settleManagedConflicts = settleManagedConflicts;
+exports.restoreLocalChanges = restoreLocalChanges;
+exports.findSpecrailsStashes = findSpecrailsStashes;
+exports.recordAfterRestore = recordAfterRestore;
+/**
+ * Proactive "Integrate locally" (proactive-local-integration): when the
+ * person's checkout of the integration branch has uncommitted work that
+ * overlaps the delivery, Specrails saves it as a git stash, advances the
+ * branch exactly as before, and re-applies it. Git effects only — the caller
+ * owns the repository lock, the decision lease and the durable record.
+ *
+ * Safety contract (never lose user work):
+ *  - the stash is identified by its COMMIT sha, never `stash@{n}`;
+ *  - it is re-applied with `git stash apply` (never `pop`) and dropped only
+ *    after a clean apply;
+ *  - a conflicting apply is rolled back ONLY on the paths the stash itself
+ *    carries that were clean right before the apply, so anything else in the
+ *    checkout (including newer edits) is untouched — and the stash is kept;
+ *  - Specrails overlay / never-stage paths are never stashed or restored.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const worktree_manager_1 = require("../../../worktree-manager");
+exports.LOCAL_STASH_MESSAGE_PREFIX = 'specrails: before integrating';
+const SHA_RE = /^[0-9a-f]{40,64}$/i;
+const PATH_CHUNK = 100;
+/**
+ * Specrails-managed generated files in the project checkout: the OpenSpec
+ * skills and slash commands that Specrails' setup (`openspec init`, run by
+ * Core) writes for every configured AI tool and that `openspec init/update`
+ * regenerates — `<tool dir>/skills/openspec-<name>/**` and
+ * `<tool dir>/{commands,prompts,workflows}/opsx…`. They are not the person's
+ * work: a conflict on one is resolved by taking the integrated (delivered)
+ * version instead of being handed to anyone. They are still saved in the
+ * stash with everything else, because `git merge --ff-only` refuses to
+ * overwrite any dirty tracked file.
+ */
+const MANAGED_GENERATED_RES = [
+    /^\.[^/]+\/skills\/openspec-[^/]+(?:\/|$)/,
+    /^\.[^/]+\/(?:commands|prompts|workflows)\/opsx(?:\/|[-.][^/]*$)/,
+];
+function isSpecrailsManagedPath(p) {
+    const normalized = p.replace(/\\/g, '/');
+    return MANAGED_GENERATED_RES.some((re) => re.test(normalized));
+}
+/** `specrails: before integrating #12, #13 (<deliveryId>)`. */
+function localStashMessage(ticketIds, deliveryId) {
+    const tickets = ticketIds.length > 0 ? ticketIds.map((id) => `#${id}`).join(', ') : 'delivery';
+    return `${exports.LOCAL_STASH_MESSAGE_PREFIX} ${tickets} (${deliveryId})`;
+}
+/** The branch the agent resolves a conflicting restore on — never the target itself. */
+function restoreBranchName(sha) {
+    return `specrails/restore-local-${sha.slice(0, 8)}`;
+}
+function excludePathspecs() {
+    return worktree_manager_1.PR_NEVER_STAGE_PATHSPEC_ROOTS.map((root) => `:(exclude)${root}`);
+}
+function literal(p) {
+    return `:(top,literal)${p}`;
+}
+function failureText(r) {
+    return (r.stderr.trim() || r.stdout.trim()).split('\n')[0] || `exit ${r.code}`;
+}
+async function safeRun(git, args, cwd) {
+    try {
+        return await git.run(args, cwd);
+    }
+    catch (err) {
+        return { code: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) };
+    }
+}
+function nulList(stdout) {
+    return stdout.split('\0').filter(Boolean);
+}
+/**
+ * The person's uncommitted paths (tracked + untracked, never ignored), minus
+ * Specrails never-stage roots. Null when status is unavailable.
+ */
+async function listUserDirtyPaths(git, repo) {
+    const r = await safeRun(git, ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--', '.', ...excludePathspecs()], repo);
+    if (r.code !== 0)
+        return null;
+    const paths = [];
+    for (const entry of nulList(r.stdout)) {
+        if (entry.length < 4)
+            continue;
+        paths.push(entry.slice(3));
+    }
+    return [...new Set(paths)];
+}
+/** Paths the delivery changes between the current head and the assembled result. */
+async function changedPathsBetween(git, repo, from, to) {
+    const r = await safeRun(git, ['diff', '--name-only', '-z', '--no-renames', from, to, '--'], repo);
+    return r.code === 0 ? nulList(r.stdout) : null;
+}
+/** True when a dirty path is (or sits under / above) a path the delivery changes. */
+function pathsOverlap(dirty, changed) {
+    if (dirty.length === 0 || changed.length === 0)
+        return false;
+    // Case-folded too: a case-insensitive filesystem (macOS/Windows default)
+    // collides `Readme.md` with `README.md`.
+    const fold = (p) => p.toLowerCase();
+    const changedSet = new Set(changed.map(fold));
+    return dirty.some((raw) => {
+        const p = fold(raw);
+        if (changedSet.has(p))
+            return true;
+        const dir = p.endsWith('/') ? p : `${p}/`;
+        return changed.some((c) => {
+            const f = fold(c);
+            return f.startsWith(dir) || p.startsWith(`${f}/`);
+        });
+    });
+}
+async function currentBranch(git, repo) {
+    const r = await safeRun(git, ['symbolic-ref', '--quiet', 'HEAD'], repo);
+    return r.code === 0 ? r.stdout.trim().replace(/^refs\/heads\//, '') : null;
+}
+async function stashTip(git, repo) {
+    const r = await safeRun(git, ['rev-parse', '--quiet', '--verify', 'refs/stash'], repo);
+    const sha = r.code === 0 ? r.stdout.trim() : '';
+    return SHA_RE.test(sha) ? sha : null;
+}
+/** `refs/stash` reflog in stash@{n} order (index = n). */
+async function listStashes(git, repo) {
+    const r = await safeRun(git, ['stash', 'list', '--format=%H%x1f%gs'], repo);
+    if (r.code !== 0)
+        return null;
+    return r.stdout.split('\n').filter(Boolean).map((line) => {
+        const [sha, subject = ''] = line.split('\x1f');
+        return { sha: sha.trim(), subject };
+    });
+}
+/**
+ * `git stash push --include-untracked` of every non-Specrails change. The new
+ * entry is proven by `refs/stash` moving to a commit whose subject carries the
+ * delivery id; nothing else is ever inferred from `stash@{0}`.
+ */
+async function saveLocalChanges(input) {
+    const { git, repo } = input;
+    const message = localStashMessage(input.ticketIds, input.deliveryId);
+    const before = await stashTip(git, repo);
+    const pushed = await safeRun(git, ['stash', 'push', '--include-untracked', '-m', message, '--', '.', ...excludePathspecs()], repo);
+    const after = await stashTip(git, repo);
+    if (!after || after === before) {
+        return { ok: false, detail: pushed.code !== 0 ? `saving local changes: ${failureText(pushed)}` : 'saving local changes: git created no stash entry' };
+    }
+    const subject = await safeRun(git, ['log', '-1', '--format=%s', after], repo);
+    if (subject.code !== 0 || !subject.stdout.includes(`(${input.deliveryId})`)) {
+        // refs/stash moved but not to our entry (a concurrent external stash):
+        // do not guess. The person's changes are in SOME stash; refuse to proceed.
+        return { ok: false, detail: 'saving local changes: the new stash entry could not be verified' };
+    }
+    const at = (input.now ?? (() => new Date().toISOString()))();
+    return {
+        ok: true,
+        record: {
+            sha: after, name: message, checkoutPath: repo, branch: input.branch, state: 'saved',
+            restoreBranch: null, conflictPaths: [], savedAt: at, updatedAt: at,
+        },
+    };
+}
+/** Every path the stash carries: index + worktree changes, and its untracked files. */
+async function stashPaths(git, repo, sha) {
+    const worktree = await safeRun(git, ['diff', '--name-only', '-z', '--no-renames', `${sha}^1`, sha, '--'], repo);
+    const index = await safeRun(git, ['diff', '--name-only', '-z', '--no-renames', `${sha}^1`, `${sha}^2`, '--'], repo);
+    if (worktree.code !== 0 || index.code !== 0)
+        return null;
+    const untracked = new Map();
+    const third = await safeRun(git, ['rev-parse', '--quiet', '--verify', `${sha}^3`], repo);
+    if (third.code === 0) {
+        const tree = await safeRun(git, ['ls-tree', '-r', '-z', `${sha}^3`], repo);
+        if (tree.code !== 0)
+            return null;
+        for (const entry of nulList(tree.stdout)) {
+            const tab = entry.indexOf('\t');
+            if (tab < 0)
+                continue;
+            const [, , blob] = entry.slice(0, tab).split(' ');
+            untracked.set(entry.slice(tab + 1), blob);
+        }
+    }
+    return { tracked: [...new Set([...nulList(worktree.stdout), ...nulList(index.stdout)])], untracked };
+}
+async function inChunks(paths, fn) {
+    for (let i = 0; i < paths.length; i += PATH_CHUNK) {
+        const r = await fn(paths.slice(i, i + PATH_CHUNK));
+        if (r.code !== 0)
+            return r;
+    }
+    return null;
+}
+/** True when the checkout already holds exactly what the stash carries (a
+ * crash between a clean apply and the drop). */
+async function alreadyApplied(git, repo, sha, carried) {
+    if (carried.tracked.length === 0 && carried.untracked.size === 0)
+        return false;
+    if (carried.tracked.length > 0) {
+        const failed = await inChunks(carried.tracked, (chunk) => safeRun(git, ['diff', '--quiet', sha, '--', ...chunk.map(literal)], repo));
+        if (failed)
+            return false;
+    }
+    for (const [file, blob] of carried.untracked) {
+        const abs = path.join(repo, file);
+        if (!fs.existsSync(abs))
+            return false;
+        const hashed = await safeRun(git, ['hash-object', '--', file], repo);
+        if (hashed.code !== 0 || hashed.stdout.trim() !== blob)
+            return false;
+    }
+    return true;
+}
+async function dropBySha(git, repo, sha) {
+    const list = await listStashes(git, repo);
+    const index = list?.findIndex((entry) => entry.sha === sha) ?? -1;
+    if (index < 0)
+        return null;
+    const dropped = await safeRun(git, ['stash', 'drop', '--quiet', `stash@{${index}}`], repo);
+    return dropped.code === 0 ? null : `dropping restored stash ${sha.slice(0, 8)}: ${failureText(dropped)}`;
+}
+/** Put the given paths back to HEAD: tracked ones from HEAD, the rest removed. */
+async function resetPathsToHead(git, repo, paths) {
+    if (paths.length === 0)
+        return null;
+    const inHead = new Set();
+    for (let i = 0; i < paths.length; i += PATH_CHUNK) {
+        const listed = await safeRun(git, ['ls-tree', '-r', '-z', '--name-only', 'HEAD', '--', ...paths.slice(i, i + PATH_CHUNK).map(literal)], repo);
+        if (listed.code !== 0)
+            return `restoring the integrated tree: ${failureText(listed)}`;
+        for (const p of nulList(listed.stdout))
+            inHead.add(p);
+    }
+    const tracked = paths.filter((p) => inHead.has(p));
+    const extra = paths.filter((p) => !inHead.has(p));
+    const checkout = await inChunks(tracked, (chunk) => safeRun(git, ['checkout', 'HEAD', '--', ...chunk.map(literal)], repo));
+    if (checkout)
+        return `restoring the integrated tree: ${failureText(checkout)}`;
+    const unstage = await inChunks(extra, (chunk) => safeRun(git, ['rm', '--cached', '-q', '--ignore-unmatch', '--', ...chunk.map(literal)], repo));
+    if (unstage)
+        return `restoring the integrated tree: ${failureText(unstage)}`;
+    for (const p of extra) {
+        const abs = path.join(repo, p);
+        try {
+            const stat = fs.lstatSync(abs);
+            if (!stat.isDirectory())
+                fs.rmSync(abs, { force: true });
+        }
+        catch { /* already absent */ }
+    }
+    return null;
+}
+async function unmergedPaths(git, cwd) {
+    const r = await safeRun(git, ['diff', '--name-only', '-z', '--diff-filter=U'], cwd);
+    return r.code === 0 ? nulList(r.stdout) : null;
+}
+/**
+ * After a conflicting `git stash apply` whose remaining conflicts are all
+ * Specrails-managed: take HEAD's (the integrated) version of those paths and
+ * unstage the rest, which leaves the tree as a clean apply would.
+ */
+async function settleManagedConflicts(git, cwd, managed, carriedTracked) {
+    const reset = await resetPathsToHead(git, cwd, managed);
+    if (reset)
+        return { ok: false, detail: reset };
+    const rest = carriedTracked.filter((p) => !managed.includes(p));
+    const unstaged = await inChunks(rest, (chunk) => safeRun(git, ['reset', '-q', '--', ...chunk.map(literal)], cwd));
+    if (unstaged)
+        return { ok: false, detail: `unstaging restored changes: ${failureText(unstaged)}` };
+    const left = await unmergedPaths(git, cwd);
+    if (!left || left.length > 0)
+        return { ok: false, detail: 'unmerged paths remain after settling managed files' };
+    return { ok: true };
+}
+/**
+ * Re-apply a recorded stash into its checkout. Idempotent: an already-applied
+ * stash is just dropped; a missing one is reported `released`.
+ */
+async function restoreLocalChanges(git, record) {
+    const repo = record.checkoutPath;
+    if (!repo || !fs.existsSync(repo))
+        return { state: 'blocked', reason: 'unavailable', detail: 'The checkout the changes were saved from no longer exists.' };
+    const list = await listStashes(git, repo);
+    if (!list)
+        return { state: 'blocked', reason: 'unavailable', detail: 'git stash list failed' };
+    if (!list.some((entry) => entry.sha === record.sha))
+        return { state: 'released', warnings: [] };
+    const branch = await currentBranch(git, repo);
+    if (branch !== record.branch) {
+        return { state: 'blocked', reason: 'wrong_branch', current: branch, detail: `The checkout is on ${branch ?? 'a detached HEAD'}, not ${record.branch}.` };
+    }
+    const carried = await stashPaths(git, repo, record.sha);
+    if (!carried)
+        return { state: 'blocked', reason: 'unavailable', detail: 'The saved changes could not be read.' };
+    if (await alreadyApplied(git, repo, record.sha, carried)) {
+        const warning = await dropBySha(git, repo, record.sha);
+        return { state: 'restored', warnings: warning ? [warning] : [] };
+    }
+    const carriedPaths = [...new Set([...carried.tracked, ...carried.untracked.keys()])];
+    const preDirty = await listUserDirtyPaths(git, repo);
+    if (!preDirty)
+        return { state: 'blocked', reason: 'unavailable', detail: 'git status failed' };
+    const preDirtySet = new Set(preDirty);
+    const busy = carriedPaths.filter((p) => preDirtySet.has(p));
+    if (busy.length > 0) {
+        // Newer edits sit on the same files: applying would mix them with the
+        // saved work and a rollback could not tell them apart. Keep both.
+        return { state: 'blocked', reason: 'dirty', detail: `These files changed again since they were saved: ${busy.slice(0, 5).join(', ')}` };
+    }
+    const applied = await safeRun(git, ['stash', 'apply', '--quiet', record.sha], repo);
+    if (applied.code === 0) {
+        const warning = await dropBySha(git, repo, record.sha);
+        return { state: 'restored', warnings: warning ? [warning] : [] };
+    }
+    const unmerged = await safeRun(git, ['diff', '--name-only', '-z', '--diff-filter=U'], repo);
+    const conflictPaths = unmerged.code === 0 ? nulList(unmerged.stdout) : [];
+    const postDirty = (await listUserDirtyPaths(git, repo)) ?? [];
+    const touched = carriedPaths.filter((p) => !preDirtySet.has(p) && (postDirty.includes(p) || conflictPaths.includes(p)));
+    if (touched.length === 0 && conflictPaths.length === 0) {
+        // Git refused before touching anything (typically: a file the stash
+        // would restore as untracked now exists, tracked, in the integrated
+        // result). The tree is intact; the stash is kept for a manual resolve.
+        const present = carriedPaths.filter((p) => fs.existsSync(path.join(repo, p)));
+        return { state: 'needs_attention', conflictPaths: (present.length > 0 ? present : carriedPaths).slice(0, 20), warnings: [] };
+    }
+    if (conflictPaths.length > 0 && conflictPaths.every(isSpecrailsManagedPath)) {
+        // Only Specrails-managed generated files conflicted (e.g. OpenSpec skills
+        // regenerated on both sides): they take the integrated version and the
+        // person's own changes stay applied, so the stash is done.
+        const managed = await settleManagedConflicts(git, repo, conflictPaths, carried.tracked);
+        if (managed.ok) {
+            const warning = await dropBySha(git, repo, record.sha);
+            return {
+                state: 'restored',
+                managedPaths: conflictPaths,
+                warnings: warning ? [warning] : [],
+            };
+        }
+    }
+    const warnings = [];
+    const restoreError = await resetPathsToHead(git, repo, carriedPaths.filter((p) => !preDirtySet.has(p)));
+    if (restoreError)
+        warnings.push(restoreError);
+    const finalDirty = await listUserDirtyPaths(git, repo);
+    if (!finalDirty || finalDirty.length !== preDirty.length || finalDirty.some((p) => !preDirtySet.has(p))) {
+        warnings.push('The integrated tree could not be fully restored after the conflicting apply; your saved changes are still in the stash.');
+    }
+    return { state: 'needs_attention', conflictPaths: (conflictPaths.length > 0 ? conflictPaths : touched).slice(0, 20), warnings };
+}
+/** Specrails stashes in a repository, keyed by delivery id (from the message). */
+async function findSpecrailsStashes(git, repo) {
+    const list = await listStashes(git, repo);
+    if (!list)
+        return [];
+    const found = [];
+    for (const entry of list) {
+        // Reflog subject: "On <branch>: <message>" (or "WIP on …").
+        const match = /^(?:WIP )?[Oo]n ([^:]+): (specrails: before integrating .*\(([^()\s]+)\))$/.exec(entry.subject);
+        if (!match || !SHA_RE.test(entry.sha))
+            continue;
+        found.push({ sha: entry.sha, branch: match[1] === '(no branch)' ? null : match[1], name: match[2], deliveryId: match[3] });
+    }
+    return found;
+}
+/** Fold a restore attempt into the durable record (pure). `blocked` keeps it `saved`. */
+function recordAfterRestore(record, result, now = new Date().toISOString()) {
+    if (result.state === 'restored' || result.state === 'released')
+        return { ...record, state: result.state, updatedAt: now };
+    if (result.state === 'needs_attention') {
+        return { ...record, state: 'needs_attention', restoreBranch: restoreBranchName(record.sha), conflictPaths: result.conflictPaths, updatedAt: now };
+    }
+    return { ...record, updatedAt: now };
+}

package/server/dist/modules/delivery/runtime/multi-repo-execution.js

@@ -16,6 +16,9 @@ const rail_pr_store_1 = require("./rail-pr-store");
 const agent_chat_registry_1 = require("../../missions/runtime/agent-chat-registry");
 const rail_pr_ticket_effects_1 = require("./rail-pr-ticket-effects");
 const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
+const flow_worktree_handoff_1 = require("./flow-worktree-handoff");
+const flow_review_outcome_1 = require("./flow-review-outcome");
+const delivery_evidence_1 = require("./delivery-evidence");
 var multi_repo_execution_store_2 = require("./multi-repo-execution-store");
 Object.defineProperty(exports, "migrateMultiRepoExecution", { enumerable: true, get: function () { return multi_repo_execution_store_2.migrateMultiRepoExecution; } });
 Object.defineProperty(exports, "getRepositoryExecutionReferences", { enumerable: true, get: function () { return multi_repo_execution_store_2.getRepositoryExecutionReferences; } });
@@ -65,6 +68,12 @@ function refreshRepositoryDeliveryGroup(db, parentId, opts = {}) {
         cleanupWarnings: children.flatMap((row) => (0, rail_pr_store_1.toPrDeliverySnapshot)(row).cleanupWarnings),
         safetyArchives: children.flatMap((row) => (0, rail_pr_store_1.toPrDeliverySnapshot)(row).safetyArchives),
     };
+    // The group's first human decision is its earliest repository decision
+    // (first write wins on the parent). Publish/merge instants are stamped by
+    // the parent's own transitions into pr_ready / merged.
+    const childDecisions = children.map((row) => row.decided_at).filter((value) => typeof value === 'string' && value.length > 0).sort();
+    if (childDecisions.length > 0)
+        patch.decidedAt = childDecisions[0];
     if (finished) {
         const successes = children.filter((row) => row.implementation_outcome === 'succeeded').length;
         patch.implementationOutcome = successes === children.length ? 'succeeded' : successes ? 'partially_succeeded' : 'failed';
@@ -95,6 +104,15 @@ function refreshRepositoryDeliveryGroup(db, parentId, opts = {}) {
             decision = 'implementation_failed';
             patch.deliveryOutcome = 'blocked';
             patch.statusCode = 'implementation_failed';
+            // A Flow → Spec group has exactly one repository: its "changes requested"
+            // outcome (status + the evidence it is read from) is the group's, so the
+            // card offers Back to Flow / Relaunch and the Flow reads its findings.
+            const only = children.length === 1 ? children[0] : null;
+            if (only && only.loop_id === flow_review_outcome_1.FLOW_SPEC_DELIVERY_LOOP_ID && only.status_code === 'review_changes_requested') {
+                patch.statusCode = 'review_changes_requested';
+                patch.statusDetail = only.status_detail;
+                patch.settleEvidence = (0, delivery_evidence_1.readSettleEvidence)(only.settle_evidence);
+            }
         }
         else if (children.some((row) => row.decision === 'pr_failed')) {
             decision = 'pr_failed';
@@ -205,6 +223,12 @@ async function launchMultiRepositoryRail(input, io = {}) {
     }
     if (input.explicitPrTarget && selected.length !== 1)
         throw new Error('An explicit pull request target must name one repository');
+    // A Flow hand-off adopts ONE worktree of ONE repository: the group must be
+    // exactly that repository (checked before any delivery row exists).
+    const flowWorktree = input.requiredFlowWorktree;
+    if (flowWorktree && (selected.length !== 1 || !flowWorktree.repositoryId || selected[0].id !== flowWorktree.repositoryId)) {
+        throw new flow_worktree_handoff_1.FlowWorktreeMismatchError('A Flow hand-off launches exactly the repository its worktree belongs to');
+    }
     const artifactRepositoryId = selected.find((repo) => repo.isPrimary)?.id ?? selected[0].id;
     const graph = structuredClone(input.loopGraph);
     for (const node of graph.nodes) {
@@ -269,6 +293,7 @@ async function launchMultiRepositoryRail(input, io = {}) {
     };
     const generation = (0, rail_pr_store_1.createPrDeliveryGeneration)(ctx.db, {
         launchConfig: input.launchConfig,
+        loopChoice: input.loopChoice ?? null,
         id: parentId, railIndex: input.railIndex, loopId: input.loopId, railKey: `${input.railIndex}-${input.loopId}`,
         ticketIds: input.ticketIds, baseBranch: input.baseBranch ?? '', loopName: input.loopName,
         originSurface: input.originSurface ?? 'dashboard', originConversationId: input.originConversationId,
@@ -394,7 +419,8 @@ async function launchMultiRepositoryRail(input, io = {}) {
                     ...(repository.workspacePath ? { workspacePath: repository.workspacePath } : {}),
                     ...(repository.workspacePaths ? { workspacePaths: [...repository.workspacePaths] } : {}),
                     ...((input.workspaceSelection?.[repository.id] ?? previousRepository?.selectedWorkspacePaths) ? { selectedWorkspacePaths: [...(input.workspaceSelection?.[repository.id] ?? previousRepository.selectedWorkspacePaths)] } : {}),
-                    gitCommonDir: (0, repo_lock_1.repositoryLockKey)(repository.path), baseBranch: child.base_branch, integrationBranch: integrationBranches.get(repository.id) ?? previousRepository?.integrationBranch ?? child.base_branch, baseSha: head.stdout.trim(),
+                    // A Flow worktree is measured from the Flow's reservation commit, never its frozen HEAD.
+                    gitCommonDir: (0, repo_lock_1.repositoryLockKey)(repository.path), baseBranch: child.base_branch, integrationBranch: integrationBranches.get(repository.id) ?? previousRepository?.integrationBranch ?? child.base_branch, baseSha: flowWorktree?.baseSha ?? head.stdout.trim(),
                     worktreePath: worktree.worktree_path, branch: worktree.branch, worktreeId: worktree.id });
             }
         }

package/server/dist/modules/delivery/runtime/phase3-harvest.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBaselineCost = runBaselineCost;
+exports.phase3HarvestOptions = phase3HarvestOptions;
+const core_capabilities_1 = require("../../agent-runtime/runtime/core-capabilities");
+const agent_runtime_history_1 = require("../../agent-runtime/runtime/agent-runtime-history");
+const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
+const domain_1 = require("../../project-rules/domain");
+const rules_store_1 = require("../../project-rules/runtime/rules-store");
+/** Baseline spend recorded in the run's runtime history (null when unknown). */
+function runBaselineCost(db, runId) {
+    try {
+        const contextPath = (0, loop_runs_store_1.readDefinitionRun)(db, runId)?.metadata.contextPath;
+        if (!contextPath)
+            return null;
+        const baseline = (0, agent_runtime_history_1.readRuntimeHistory)(contextPath)?.efficiencySummary?.baseline;
+        return baseline ? { invocations: baseline.invocations, costUsd: baseline.costUsd, inputTokens: baseline.inputTokens, outputTokens: baseline.outputTokens } : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function phase3HarvestOptions(input) {
+    const capabilities = await (input.capabilities ?? core_capabilities_1.corePhase3Capabilities)();
+    let humanRules = null;
+    if (capabilities.rulesInventory) {
+        try {
+            humanRules = (0, domain_1.humanOnlyRules)((0, rules_store_1.readProjectRulesInventory)(input.project));
+        }
+        catch {
+            humanRules = null;
+        }
+    }
+    return {
+        specTrace: capabilities.specTrace,
+        baselineOnTouch: capabilities.baselineOnTouch,
+        humanRules,
+        ...(capabilities.baselineOnTouch ? { baselineCost: (runId) => runBaselineCost(input.db, runId) } : {}),
+    };
+}

package/server/dist/modules/delivery/runtime/pr-body.js

@@ -4,6 +4,8 @@ exports.isTestFilePath = isTestFilePath;
 exports.collectBranchChanges = collectBranchChanges;
 exports.parseShortstat = parseShortstat;
 exports.parseNameStatus = parseNameStatus;
+exports.buildReviewBriefBlock = buildReviewBriefBlock;
+exports.buildDerivationLine = buildDerivationLine;
 exports.buildCanonicalPrBody = buildCanonicalPrBody;
 exports.extractSpecNarrative = extractSpecNarrative;
 const explore_contract_refine_1 = require("../../conversations/runtime/explore-contract-refine");
@@ -71,11 +73,59 @@ function parseNameStatus(stdout) {
     }
     return paths;
 }
+const BRIEF_LIST_MAX = 10;
+const SEVERITY_LABEL = { high: 'High', medium: 'Medium', low: 'Low' };
+/**
+ * Short "What to look at" block under the summary: high and medium risks,
+ * untested paths and human checks. Low risks, behaviour changes and invariants
+ * stay in the review packet. Returns null when there is nothing to list.
+ */
+function buildReviewBriefBlock(brief) {
+    if (!brief)
+        return null;
+    const risks = brief.risks.filter((risk) => risk.severity === 'high' || risk.severity === 'medium').slice(0, BRIEF_LIST_MAX);
+    const untested = brief.untested.slice(0, BRIEF_LIST_MAX);
+    const checks = brief.humanChecks.map(cleanInline).filter(Boolean).slice(0, BRIEF_LIST_MAX);
+    if (risks.length === 0 && untested.length === 0 && checks.length === 0)
+        return null;
+    const chunks = ['## What to look at', '_Advisory brief from the AI reviewer: where a human should look first. It is not a verification result._'];
+    if (risks.length > 0) {
+        chunks.push('**Risks**', risks.map((risk) => {
+            const area = risk.area ? ` · ${cleanInline(risk.area)}` : '';
+            const ref = risk.ref ? ` (${codeSpan(risk.ref)})` : '';
+            return `- **${SEVERITY_LABEL[risk.severity]}**${area} — ${cleanInline(risk.whatToLookAt)}${ref}`;
+        }).join('\n'));
+    }
+    if (untested.length > 0) {
+        chunks.push('**Untested paths**', untested.map((entry) => `- ${codeSpan(entry.path)}${entry.why ? ` — ${cleanInline(entry.why)}` : ''}`).join('\n'));
+    }
+    if (checks.length > 0) {
+        chunks.push('**Human checks**', checks.map((check) => `- [ ] ${check}`).join('\n'));
+    }
+    return chunks.join('\n\n');
+}
+function codeSpan(raw) {
+    return `\`${cleanInline(raw).replace(/`/g, "'")}\``;
+}
+/** `> Derived from a Flow session: change X, N/M changed files explained (K unexplained).` */
+function buildDerivationLine(derivation) {
+    if (!derivation)
+        return null;
+    const unexplained = derivation.unexplainedFiles.length + derivation.unexplainedOmitted;
+    const change = derivation.change ? ` OpenSpec change \`${derivation.change}\`,` : '';
+    return `> Derived from a Flow session:${change} ${derivation.explained}/${derivation.files} changed files explained by its design${unexplained > 0 ? ` (${unexplained} unexplained — see the review packet)` : ''}.`;
+}
 function buildCanonicalPrBody(input) {
     const parts = [summaryParagraph(input)];
+    const briefBlock = buildReviewBriefBlock(input.reviewBrief);
+    if (briefBlock)
+        parts.push(briefBlock);
     for (const t of input.tickets) {
         parts.push(ticketSection(t, input.changes ?? null));
     }
+    const derivationLine = buildDerivationLine(input.derivation ?? null);
+    if (derivationLine)
+        parts.push(derivationLine);
     const changesSection = buildChangesSection(input.changes ?? null);
     if (changesSection)
         parts.push(changesSection);