specrails-desktop 2.64.1 → 2.65.0

package/server/dist/modules/delivery/runtime/delivery-evidence.js

@@ -1,4 +1,37 @@
 "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;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -8,8 +41,13 @@ exports.extractVerifyStepText = extractVerifyStepText;
 exports.parseConfidenceScore = parseConfidenceScore;
 exports.harvestDeliveryEvidence = harvestDeliveryEvidence;
 exports.readRuntimeEvidence = readRuntimeEvidence;
+exports.readFindingLocations = readFindingLocations;
+exports.definitionReviewBrief = definitionReviewBrief;
 exports.projectDefinitionRuntimeEvidence = projectDefinitionRuntimeEvidence;
+exports.parseDerivation = parseDerivation;
+exports.readDerivationFile = readDerivationFile;
 exports.healRuntimeEvidence = healRuntimeEvidence;
+exports.coreAnnouncesReviewBrief = coreAnnouncesReviewBrief;
 exports.readSettleEvidence = readSettleEvidence;
 /**
  * Deterministic settle-time evidence harvest for the review packet
@@ -28,6 +66,8 @@ const loop_factory_1 = require("../../loops/runtime/loop-factory");
 const verification_sentinel_1 = require("../../execution/runtime/verification-sentinel");
 var verification_sentinel_2 = require("../../execution/runtime/verification-sentinel");
 Object.defineProperty(exports, "parseVerificationSentinel", { enumerable: true, get: function () { return verification_sentinel_2.parseVerificationSentinel; } });
+const review_brief_1 = require("./review-brief");
+const run_records_1 = require("./run-records");
 /** Bounded tail of the verify step's raw output persisted per unit. */
 exports.VERIFY_TAIL_CAP = 4096;
 /** Raw confidence-score.json payloads are capped before persistence. */
@@ -327,6 +367,14 @@ function harvestDeliveryEvidence(io, units) {
                 const runtime = unit.definitionStatus
                     ? projectDefinitionRuntimeEvidence(unit.definitionStatus, unit.reviewerStepId)
                     : readRuntimeEvidence(unit.runtimeDir, unit.runId, fsIo);
+                if (runtime && !runtime.derivation && runtime.derivationPath) {
+                    // Core keeps the full report next to the node's artifacts.
+                    const derivation = readDerivationFile(runtime.derivationPath, fsIo);
+                    if (derivation) {
+                        runtime.derivation = derivation;
+                        delete runtime.derivationPath;
+                    }
+                }
                 if (unit.definitionStatus)
                     evidence.runtime = runtime;
                 if (runtime) {
@@ -349,6 +397,33 @@ function harvestDeliveryEvidence(io, units) {
         catch {
             unitErrored = true;
         }
+        if (io.reviewBrief) {
+            try {
+                const brief = readUnitReviewBrief(unit, evidence, fsIo);
+                if (brief)
+                    evidence.reviewBrief = brief;
+            }
+            catch {
+                unitErrored = true;
+            }
+        }
+        const recordsDir = unit.recordsDir ?? unit.runtimeDir;
+        if (recordsDir && (io.specTrace || io.baselineOnTouch)) {
+            try {
+                const trace = io.specTrace ? (0, run_records_1.readSpecTrace)(recordsDir, fsIo) : null;
+                if (trace)
+                    evidence.specTrace = trace;
+                const baseline = io.baselineOnTouch ? (0, run_records_1.readBaseline)(recordsDir, fsIo) : null;
+                if (baseline) {
+                    baseline.capabilities = (0, run_records_1.baselineCapabilities)(trace);
+                    baseline.cost = unit.runId ? io.baselineCost?.(unit.runId) ?? null : null;
+                    evidence.baseline = baseline;
+                }
+            }
+            catch {
+                unitErrored = true;
+            }
+        }
         if (unitErrored)
             errored++;
         return evidence;
@@ -358,6 +433,7 @@ function harvestDeliveryEvidence(io, units) {
         harvest: units.length > 0 && errored === units.length ? 'failed' : errored > 0 ? 'partial' : 'ok',
         harvestedAt: (io.now?.() ?? new Date()).toISOString(),
         units: harvested,
+        ...(io.humanRules?.length ? { humanRules: io.humanRules.slice(0, 100) } : {}),
     };
 }
 const RUNTIME_OUTPUT_TAIL_CAP = 1500;
@@ -433,6 +509,7 @@ function readRuntimeEvidence(runtimeDir, runId, fsIo) {
         checks.push({ name, status: str(raw.status, 40) ?? 'unknown', required: raw.required === true, hostRun, evidence, scope: str(raw.scope), limitations: str(raw.limitations) });
     }
     const findings = strList(acceptance?.findings, 6);
+    const findingLocations = readFindingLocations(acceptance?.findings, acceptance?.findingLocations, 6);
     const checkpoint = readJson(fsIo, path_1.default.join(runtimeDir, 'agent-workflow', runId, 'checkpoint.json'));
     const steps = isRecord(checkpoint) && isRecord(checkpoint.state) && isRecord(checkpoint.state.steps) ? checkpoint.state.steps : null;
     const reviewer = steps && isRecord(steps.reviewer) ? steps.reviewer : null;
@@ -440,7 +517,35 @@ function readRuntimeEvidence(runtimeDir, runId, fsIo) {
     const review = parseRuntimeReview(output);
     if (commands.length === 0 && checks.length === 0 && findings.length === 0 && !review)
         return null;
-    return { commands, checks, findings, review };
+    return { commands, checks, findings, ...(findingLocations.length ? { findingLocations } : {}), review };
+}
+/**
+ * Core's `acceptance.findingLocations` (contract 5.9), re-indexed onto the kept
+ * findings and re-validated: an anchor is advisory, so a malformed one (or one
+ * for a finding the cap dropped) disappears instead of failing the harvest.
+ * Older Core never writes the field, so older runs read as unanchored.
+ */
+function readFindingLocations(rawFindings, rawLocations, cap) {
+    if (!Array.isArray(rawFindings) || !Array.isArray(rawLocations))
+        return [];
+    const kept = [];
+    rawFindings.forEach((entry, index) => { if (typeof entry === 'string' && entry.trim() && kept.length < cap)
+        kept.push(index); });
+    const seen = new Set();
+    const out = [];
+    for (const raw of rawLocations) {
+        if (!isRecord(raw))
+            continue;
+        const position = typeof raw.finding === 'number' ? kept.indexOf(raw.finding) : -1;
+        const filePath = typeof raw.path === 'string' ? raw.path.trim().replace(/\\/g, '/').replace(/^\.\//, '') : '';
+        if (position < 0 || seen.has(position) || !filePath || filePath.length > 500 || filePath.startsWith('/') || /^[A-Za-z]:/.test(filePath) || filePath.includes('\0') || filePath.split('/').includes('..'))
+            continue;
+        const line = typeof raw.line === 'number' && Number.isInteger(raw.line) && raw.line >= 1 ? raw.line : undefined;
+        const endLine = line !== undefined && typeof raw.endLine === 'number' && Number.isInteger(raw.endLine) && raw.endLine > line ? raw.endLine : undefined;
+        seen.add(position);
+        out.push({ finding: position, path: filePath, ...(line !== undefined ? { line } : {}), ...(endLine !== undefined ? { endLine } : {}) });
+    }
+    return out;
 }
 /** A reviewer verdict stays AI-reported; it cannot create host verification. */
 function parseRuntimeReview(value) {
@@ -465,12 +570,59 @@ function parseRuntimeReview(value) {
     }
     return null;
 }
+/**
+ * The reviewer's risk brief for one unit, in source order:
+ *  1. `<pipelineDir>/<runId>/review-brief.json` (engine 1, rewritten at every verdict);
+ *  2. the engine 2 reviewer output in the committed definition scopes
+ *     (`implementation` → `review.brief`, reviewer step, reviewer role turn);
+ *  3. `confidence-score.json` → `brief` (approved verdicts only).
+ * Returns null when no source carries a brief record.
+ */
+function readUnitReviewBrief(unit, evidence, fsIo) {
+    if (unit.runtimeDir) {
+        const file = path_1.default.join(unit.runtimeDir, review_brief_1.REVIEW_BRIEF_FILE);
+        if (fsIo.fileExists(file))
+            return (0, review_brief_1.parseReviewBriefRecord)(fsIo.readFile(file));
+    }
+    if (unit.definitionStatus) {
+        const fromDefinition = definitionReviewBrief(unit.definitionStatus, unit.reviewerStepId);
+        if (fromDefinition)
+            return fromDefinition;
+    }
+    const raw = evidence.confidence?.raw;
+    if (isRecord(raw) && raw.brief !== undefined) {
+        const record = (0, review_brief_1.reviewBriefFromReviewerOutput)({ ...raw, approved: true, score: evidence.confidence?.overall ?? null }, 'confidence-score');
+        if (record)
+            return record;
+    }
+    return null;
+}
+/** Latest reviewer brief found in committed definition scopes (null when none). */
+function definitionReviewBrief(status, reviewerStepId) {
+    if (status.status === 'unavailable' || !status.scopes)
+        return null;
+    let found = null;
+    for (const scope of status.scopes) {
+        if (!['succeeded', 'failed'].includes(scope.status) || !isRecord(scope.output))
+            continue;
+        const output = scope.output;
+        const reviewer = scope.kind === 'implementation' ? output.review
+            : scope.kind === 'implementation-step' && output.phase === 'reviewer' ? output
+                : reviewerStepId === scope.nodePath && scope.kind === 'role-turn' ? (output.structured ?? output) : null;
+        const record = (0, review_brief_1.reviewBriefFromReviewerOutput)(reviewer);
+        if (record)
+            found = record;
+    }
+    return found;
+}
 /** Pure projection of exact committed scopes; never read Core's private database. */
 function projectDefinitionRuntimeEvidence(status, reviewerStepId) {
     if (status.status === 'unavailable' || !status.scopes)
         return null;
     const commands = [];
     const scopedReviews = [];
+    let derivation = null;
+    let derivationPath = null;
     for (const scope of status.scopes) {
         if (!['succeeded', 'failed'].includes(scope.status) || !scope.attemptId || !isRecord(scope.output))
             continue;
@@ -486,6 +638,18 @@ function projectDefinitionRuntimeEvidence(status, reviewerStepId) {
                     durationMs: null, required: true, hostRun: true, outputTail: null });
             }
         }
+        if (scope.kind === 'derive-change') {
+            // The latest derive attempt wins (a repair visit supersedes the rejected one).
+            const parsed = parseDerivation(output.derivation);
+            if (parsed) {
+                derivation = parsed;
+                derivationPath = null;
+            }
+            else if (typeof output.derivationPath === 'string' && output.derivationPath.length < 4096) {
+                derivation = null;
+                derivationPath = output.derivationPath;
+            }
+        }
         const review = scope.status !== 'succeeded' ? null : scope.kind === 'implementation' ? parseRuntimeReview(output.review)
             : scope.kind === 'implementation-step' && output.phase === 'reviewer' ? parseRuntimeReview(output)
                 : reviewerStepId === scope.nodePath && scope.kind === 'role-turn' ? parseRuntimeReview(output.structured ?? output) : null;
@@ -496,7 +660,45 @@ function projectDefinitionRuntimeEvidence(status, reviewerStepId) {
     // Keep that absence explicit instead of letting the last branch win.
     const review = scopedReviews.length === 1 ? scopedReviews[0].review : null;
     const findings = scopedReviews.length > 1 ? ['Multiple scoped reviewer verdicts; no aggregate confidence score is defined.'] : [];
-    return commands.length || review || findings.length ? { commands, checks: [], findings, review, scopedReviews } : null;
+    if (!commands.length && !review && !findings.length && !derivation && !derivationPath)
+        return null;
+    return { commands, checks: [], findings, review, scopedReviews, ...(derivation ? { derivation } : {}), ...(derivationPath ? { derivationPath } : {}) };
+}
+const DERIVATION_FILE_CAP = 512 * 1024;
+const DERIVATION_UNEXPLAINED_CAP = 200;
+const count = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : 0;
+/** Parse Core's derivation report (inline node output or derivation.json). Null when it is not one. */
+function parseDerivation(value) {
+    if (!isRecord(value) || typeof value.files !== 'number' || typeof value.explained !== 'number')
+        return null;
+    const listed = Array.isArray(value.unexplainedFiles) ? value.unexplainedFiles.filter((file) => typeof file === 'string' && file.length > 0) : [];
+    const confidence = value.confidence === 'high' || value.confidence === 'medium' || value.confidence === 'low' ? value.confidence : null;
+    return {
+        change: str(value.change, 128),
+        files: count(value.files),
+        explained: Math.min(count(value.explained), count(value.files)),
+        unexplainedFiles: listed.slice(0, DERIVATION_UNEXPLAINED_CAP).map((file) => file.slice(0, 512)),
+        unexplainedOmitted: Math.max(0, listed.length - DERIVATION_UNEXPLAINED_CAP) + count(value.unexplainedOmitted),
+        confidence,
+        requirementsAdded: count(value.requirementsAdded),
+        requirementsModified: count(value.requirementsModified),
+        tasks: count(value.tasks),
+        transcriptTurnsUsed: count(value.transcriptTurnsUsed),
+    };
+}
+/** Read a derivation.json Core wrote (bounded; null when absent or invalid). */
+function readDerivationFile(file, fsIo) {
+    try {
+        if (!fsIo.fileExists(file))
+            return null;
+        const raw = fsIo.readFile(file);
+        if (raw.length > DERIVATION_FILE_CAP)
+            return null;
+        return parseDerivation(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Heal a persisted settle evidence whose units predate the runtime harvest:
@@ -504,7 +706,7 @@ function projectDefinitionRuntimeEvidence(status, reviewerStepId) {
  * now. Returns the healed evidence when anything was added, else null (so the
  * caller neither rewrites the row nor re-broadcasts). Pure apart from `fsIo`.
  */
-function healRuntimeEvidence(evidence, pipelineDir, fsIo = {}, definitionStatuses = new Map()) {
+function healRuntimeEvidence(evidence, pipelineDir, fsIo = {}, definitionStatuses = new Map(), options = {}) {
     const io = {
         readFile: fsIo.readFile ?? ((p) => fs_1.default.readFileSync(p, 'utf8')),
         listDir: fsIo.listDir ?? ((p) => fs_1.default.readdirSync(p)),
@@ -513,10 +715,36 @@ function healRuntimeEvidence(evidence, pipelineDir, fsIo = {}, definitionStatuse
     };
     let changed = false;
     const units = evidence.units.map((unit) => {
-        if (!unit.runId || unit.runtime)
+        const healed = healUnitRuntime(unit);
+        if (!options.reviewBrief || !healed.runId || healed.reviewBrief)
+            return healed;
+        // Deliveries settled before the brief harvest (or recovered without a
+        // pipeline dir) pick the brief up once the Core that wrote it is active.
+        let reviewBrief = null;
+        try {
+            reviewBrief = readUnitReviewBrief({
+                ticketId: healed.ticketId, runId: healed.runId, worktreePath: null,
+                runtimeDir: path_1.default.join(pipelineDir, healed.runId),
+                definitionStatus: definitionStatuses.get(healed.runId), reviewerStepId: healed.reviewerStepId,
+            }, healed, io);
+        }
+        catch {
+            reviewBrief = null;
+        }
+        if (!reviewBrief)
+            return healed;
+        changed = true;
+        return { ...healed, reviewBrief };
+    });
+    return changed ? { ...evidence, units } : null;
+    function healUnitRuntime(unit) {
+        // `refreshMissingReview`: a unit harvested without the reviewer verdict
+        // (e.g. the retained ledger was unreadable at settle) reads it again.
+        const refresh = options.refreshMissingReview === true && !!unit.runtime && !unit.runtime.review;
+        if (!unit.runId || unit.runtime && !refresh)
             return unit;
         const definition = definitionStatuses.get(unit.runId);
-        if (definition?.status === 'unavailable' || !definition && unit.runtime !== undefined)
+        if (definition?.status === 'unavailable' || !definition && unit.runtime !== undefined && !refresh)
             return unit;
         let runtime = null;
         try {
@@ -525,15 +753,28 @@ function healRuntimeEvidence(evidence, pipelineDir, fsIo = {}, definitionStatuse
         catch {
             runtime = null;
         }
-        if (!runtime)
+        if (!runtime || refresh && !runtime.review)
             return unit;
         changed = true;
         const confidence = unit.confidence ?? (runtime.review && runtime.review.score !== null
             ? { changeName: null, overall: runtime.review.score, aspects: runtime.review.aspects, flags: runtime.review.issues, raw: null }
             : null);
         return { ...unit, runtime, confidence };
-    });
-    return changed ? { ...evidence, units } : null;
+    }
+}
+/**
+ * Whether the active Core announces the reviewer risk brief (`reviewBrief: 1`
+ * from `runtime api`). Any failure reads as "not announced", so an older or
+ * missing Core leaves settle evidence exactly as it was.
+ */
+async function coreAnnouncesReviewBrief() {
+    try {
+        const { loadCoreAgentRuntime } = await Promise.resolve().then(() => __importStar(require('../../agent-runtime/runtime/agent-runtime-loader')));
+        return (await loadCoreAgentRuntime()).api?.capabilities?.reviewBrief === 1;
+    }
+    catch {
+        return false;
+    }
 }
 /** Parse a persisted settle_evidence column value (null-tolerant). */
 function readSettleEvidence(raw) {

package/server/dist/modules/delivery/runtime/flow-review-legacy.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listLegacyFlowReviewCandidates = listLegacyFlowReviewCandidates;
+exports.persistLegacyFlowReview = persistLegacyFlowReview;
+exports.healLegacyFlowReviews = healLegacyFlowReviews;
+const delivery_evidence_1 = require("./delivery-evidence");
+const flow_review_outcome_1 = require("./flow-review-outcome");
+const rail_pr_store_1 = require("./rail-pr-store");
+function parseList(raw) {
+    try {
+        const parsed = JSON.parse(raw ?? '[]');
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Every legacy candidate (Flow → Spec, implementation_failed, not yet a review outcome). */
+function listLegacyFlowReviewCandidates(db) {
+    return db.prepare(`
+    SELECT * FROM rail_pr_deliveries
+     WHERE loop_id = ? AND decision = 'implementation_failed' AND implementation_outcome = 'failed'
+       AND COALESCE(status_code, '') NOT IN ('review_changes_requested', 'returned_to_flow')
+     ORDER BY created_at ASC, rowid ASC
+  `).all(flow_review_outcome_1.FLOW_SPEC_DELIVERY_LOOP_ID).filter(flow_review_outcome_1.isLegacyFlowReviewCandidate);
+}
+/**
+ * Persist the reclassification of ONE row (optionally with healed evidence)
+ * in one transaction: the evidence and the status move together or not at
+ * all. False when the row is not a candidate, is busy, or its evidence does
+ * not show requested changes (the evidence is then left untouched too).
+ */
+function persistLegacyFlowReview(db, deliveryId, healedEvidence) {
+    return db.transaction(() => {
+        const stored = (0, rail_pr_store_1.getPrDelivery)(db, deliveryId);
+        if (!stored || !(0, flow_review_outcome_1.isLegacyFlowReviewCandidate)(stored) || stored.operation_token || stored.operation)
+            return false;
+        const row = healedEvidence ? { ...stored, settle_evidence: JSON.stringify(healedEvidence) } : stored;
+        const reclassified = (0, flow_review_outcome_1.legacyFlowReviewReclassification)(row, parseList(row.branches));
+        if (!reclassified)
+            return false;
+        return (0, rail_pr_store_1.transitionDecision)(db, row.id, 'implementation_failed', 'implementation_failed', {
+            ...(healedEvidence ? { settleEvidence: healedEvidence } : {}),
+            statusCode: reclassified.statusCode,
+            statusDetail: reclassified.statusDetail,
+            branches: reclassified.units,
+        });
+    })();
+}
+/** Evidence for a row whose settle harvest stored nothing: one bare unit per run. */
+function bareEvidence(row) {
+    const runIds = parseList(row.run_ids).filter((id) => typeof id === 'string' && id.length > 0);
+    const ticketIds = parseList(row.ticket_ids);
+    if (runIds.length === 0)
+        return null;
+    return {
+        schemaVersion: 1, harvest: 'partial', harvestedAt: new Date().toISOString(),
+        units: runIds.map((runId, index) => ({ ticketId: ticketIds[index] ?? ticketIds[0] ?? 0, runId, sentinel: 'absent', sentinelDetail: null, verifyTail: null, confidence: null })),
+    };
+}
+/**
+ * Reclassify every legacy candidate whose evidence (stored, or re-read from
+ * the retained run) shows requested changes. Returns the reclassified ids so
+ * the caller re-projects their cards. Never throws.
+ */
+async function healLegacyFlowReviews(deps) {
+    const reclassified = [];
+    let candidates;
+    try {
+        candidates = listLegacyFlowReviewCandidates(deps.db);
+    }
+    catch {
+        return reclassified;
+    }
+    for (const row of candidates) {
+        try {
+            if ((0, flow_review_outcome_1.legacyFlowReviewReclassification)(row, [])) {
+                if (persistLegacyFlowReview(deps.db, row.id))
+                    reclassified.push(row.id);
+                continue;
+            }
+            const stored = (0, delivery_evidence_1.readSettleEvidence)(row.settle_evidence) ?? bareEvidence(row);
+            if (!stored)
+                continue;
+            const missing = stored.units.filter((unit) => unit.runId && !unit.runtime?.review).map((unit) => unit.runId);
+            if (missing.length === 0)
+                continue;
+            const definitionIds = missing.filter((runId) => deps.isDefinitionRun(runId));
+            const statuses = definitionIds.length > 0 ? await deps.probe(definitionIds) : new Map();
+            const healed = (0, delivery_evidence_1.healRuntimeEvidence)(stored, deps.pipelineDir, {}, statuses, { refreshMissingReview: true });
+            if (healed && persistLegacyFlowReview(deps.db, row.id, healed))
+                reclassified.push(row.id);
+        }
+        catch (error) {
+            console.warn(`[flow-review] legacy reclassification skipped for ${row.id}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return reclassified;
+}

package/server/dist/modules/delivery/runtime/flow-review-outcome.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOW_REVIEW_ISSUES_CAP = exports.FLOW_SPEC_DELIVERY_LOOP_ID = void 0;
+exports.flowReviewOutcome = flowReviewOutcome;
+exports.flowReviewStatusDetail = flowReviewStatusDetail;
+exports.isLegacyFlowReviewCandidate = isLegacyFlowReviewCandidate;
+exports.readFlowReviewOutcome = readFlowReviewOutcome;
+exports.legacyFlowReviewReclassification = legacyFlowReviewReclassification;
+/** `factory:flow-spec` (loops' FLOW_SPEC_LOOP_ID; a literal keeps this store-level module free of the loop catalog's imports — a test pins the equality). */
+exports.FLOW_SPEC_DELIVERY_LOOP_ID = 'factory:flow-spec';
+exports.FLOW_REVIEW_ISSUES_CAP = 20;
+const ISSUE_TEXT_CAP = 600;
+const SUMMARY_CAP = 1200;
+const COMMAND_CAP = 200;
+const clip = (text, cap) => {
+    const clean = text.trim();
+    return clean.length <= cap ? clean : `${clean.slice(0, cap).trimEnd()}…`;
+};
+function unitOutcome(unit) {
+    const runtime = unit?.runtime;
+    if (!runtime)
+        return null;
+    const failingChecks = runtime.commands
+        .filter((command) => command.outcome === 'failed' || (command.exitCode !== null && command.exitCode !== 0))
+        .slice(0, 10)
+        .map((command) => ({ command: clip(command.label, COMMAND_CAP), exitCode: command.exitCode }));
+    const review = runtime.review;
+    const rejected = review !== null && review.approved === false;
+    if (!rejected && failingChecks.length === 0)
+        return null;
+    const issues = rejected ? review.issues.filter((issue) => issue.trim()) : [];
+    return {
+        reason: rejected ? 'review' : 'check',
+        summary: review?.summary ? clip(review.summary, SUMMARY_CAP) : null,
+        issues: issues.slice(0, exports.FLOW_REVIEW_ISSUES_CAP).map((issue) => clip(issue, ISSUE_TEXT_CAP)),
+        issuesOmitted: Math.max(0, issues.length - exports.FLOW_REVIEW_ISSUES_CAP),
+        score: rejected && typeof review.score === 'number' ? review.score : null,
+        failingChecks,
+    };
+}
+/**
+ * The outcome of a FAILED Flow → Spec delivery whose evidence shows changes
+ * are still requested; null for every other loop, a succeeded run, or a
+ * failure the evidence does not explain (derivation, provider, crash), which
+ * keeps its generic failure presentation.
+ */
+function flowReviewOutcome(input) {
+    if (input.loopId !== exports.FLOW_SPEC_DELIVERY_LOOP_ID || input.implementationOutcome !== 'failed')
+        return null;
+    // Flow hands off exactly one spec: one unit.
+    return unitOutcome(input.evidence?.units?.[0]);
+}
+/** One line for `statusDetail` (and the mission briefing): what still blocks the delivery. */
+function flowReviewStatusDetail(outcome) {
+    if (outcome.reason === 'check') {
+        const checks = outcome.failingChecks.map((check) => `${check.command}${check.exitCode !== null ? ` (exit ${check.exitCode})` : ''}`).join('; ');
+        return clip(`Flow → Spec stopped: the checks still fail after the automatic correction rounds — ${checks}`, SUMMARY_CAP);
+    }
+    const first = outcome.issues[0];
+    const more = outcome.issues.length + outcome.issuesOmitted - 1;
+    return clip(`The reviewer requested changes${outcome.score !== null ? ` (score ${outcome.score})` : ''}: ${first ?? outcome.summary ?? 'see the review'}${more > 0 ? ` (+${more} more)` : ''}`, SUMMARY_CAP);
+}
+const REVIEW_STATUS_CODES = new Set(['review_changes_requested', 'returned_to_flow']);
+/**
+ * A Flow → Spec delivery settled as a generic implementation failure — before
+ * settlement classified requested changes (or with evidence healed later).
+ * Its stored evidence decides on read whether it is really a review outcome;
+ * a failure the evidence does not explain stays a failure.
+ */
+function isLegacyFlowReviewCandidate(row) {
+    return row.loop_id === exports.FLOW_SPEC_DELIVERY_LOOP_ID
+        && row.decision === 'implementation_failed'
+        && row.implementation_outcome === 'failed'
+        && !REVIEW_STATUS_CODES.has(row.status_code ?? '');
+}
+/** Parse the stored settle evidence of a row; null when absent or unreadable. */
+function readFlowReviewOutcome(row) {
+    if (row.loop_id !== exports.FLOW_SPEC_DELIVERY_LOOP_ID || !row.settle_evidence)
+        return null;
+    if (!REVIEW_STATUS_CODES.has(row.status_code ?? '') && !isLegacyFlowReviewCandidate(row))
+        return null;
+    try {
+        return flowReviewOutcome({ loopId: row.loop_id, implementationOutcome: row.implementation_outcome ?? null, evidence: JSON.parse(row.settle_evidence) });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The presentation of a legacy candidate whose evidence shows requested
+ * changes: exactly what a settlement records today (status code, detail, the
+ * per-unit failure code). Null when the row is not such a candidate. Pure —
+ * the snapshot applies it on read; the one-shot heal persists the same values.
+ */
+function legacyFlowReviewReclassification(row, units) {
+    if (!isLegacyFlowReviewCandidate(row))
+        return null;
+    const flowReview = readFlowReviewOutcome(row);
+    if (!flowReview)
+        return null;
+    return {
+        flowReview,
+        statusCode: 'review_changes_requested',
+        statusDetail: flowReviewStatusDetail(flowReview),
+        units: units.map((unit) => unit.failureCode === 'settlement_interrupted' ? ({ ...unit, failureCode: 'review_changes_requested' }) : unit),
+    };
+}

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

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Flow -> rail worktree hand-off contract (Flow mode, arch section 4.4).
+ *
+ * While a Flow is live its worktree is owned by `flow_sessions`, never by
+ * `rail_worktrees`. A rail launch adopts it through `requiredFlowWorktree`:
+ * the worktree is reused exactly (same mount, branch and frozen HEAD) and the
+ * ownership transfer — the `rail_worktrees` row plus the Flow's own state —
+ * commits in ONE SQLite transaction that delivery owns. Flow supplies only the
+ * callbacks below; delivery never issues SQL against Flow's table and Flow
+ * never imports delivery's launch internals.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowHandOffNotReadyError = exports.FlowWorktreeMismatchError = void 0;
+/** The mount, branch or HEAD differs from what the Flow froze (HTTP 409). */
+class FlowWorktreeMismatchError extends Error {
+    code = 'flow_worktree_mismatch';
+    constructor(message) {
+        super(message);
+        this.name = 'FlowWorktreeMismatchError';
+    }
+}
+exports.FlowWorktreeMismatchError = FlowWorktreeMismatchError;
+/** The Flow is not waiting for this hand-off (HTTP 409). */
+class FlowHandOffNotReadyError extends Error {
+    code = 'flow_handoff_not_ready';
+    constructor(message) {
+        super(message);
+        this.name = 'FlowHandOffNotReadyError';
+    }
+}
+exports.FlowHandOffNotReadyError = FlowHandOffNotReadyError;