specrails-desktop 2.64.2 → 2.65.0

package/server/dist/modules/delivery/runtime/review-packet.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DRIFT_REVISION_COUNT = exports.DRIFT_COST_SHARE = exports.MAX_VERSION_CHAIN = exports.HUMAN_REVIEW_BAND = void 0;
+exports.DRIFT_REVISION_COUNT = exports.DRIFT_COST_SHARE = exports.MAX_VERSION_CHAIN = exports.HUMAN_REVIEW_BAND = exports.buildWhatToLookAt = void 0;
 exports.selectVariant = selectVariant;
 exports.computeDriftNudges = computeDriftNudges;
+exports.packetDerivation = packetDerivation;
 exports.composeReviewPacket = composeReviewPacket;
 exports.packetHasUnsourcedNumericClaim = packetHasUnsourcedNumericClaim;
 /**
@@ -37,10 +38,33 @@ exports.packetHasUnsourcedNumericClaim = packetHasUnsourcedNumericClaim;
 const pr_follow_up_1 = require("./pr-follow-up");
 const spec_addenda_core_1 = require("../../specs/runtime/spec-addenda-core");
 const delivery_evidence_1 = require("./delivery-evidence");
+const run_records_1 = require("./run-records");
+const loop_factory_1 = require("../../loops/runtime/loop-factory");
 const rail_pr_store_1 = require("./rail-pr-store");
 const pr_body_1 = require("./pr-body");
+const review_brief_1 = require("./review-brief");
+var review_brief_2 = require("./review-brief");
+Object.defineProperty(exports, "buildWhatToLookAt", { enumerable: true, get: function () { return review_brief_2.buildWhatToLookAt; } });
 const ai_invocations_1 = require("../../accounting/runtime/ai-invocations");
 const project_repository_provenance_1 = require("../../../project-repository-provenance");
+const sqlite_1 = require("../../audit/adapters/sqlite");
+function agentActionsForRuns(db, runIds) {
+    const ids = [...new Set(runIds.filter((id) => typeof id === 'string' && id.length > 0))];
+    if (ids.length === 0)
+        return null;
+    try {
+        const store = (0, sqlite_1.createSqliteAgentActionStore)(db);
+        const counts = store.countByKind(ids);
+        const total = Object.values(counts).reduce((sum, value) => sum + value, 0);
+        if (total === 0)
+            return null;
+        const withRows = ids.filter((id) => Object.values(store.countByKind([id])).some((value) => value > 0));
+        return { counts, total, runIds: withRows };
+    }
+    catch {
+        return null;
+    }
+}
 const TEST_FILE_RE = /(\.test\.|\.spec\.|(^|\/)__tests__\/)/;
 function churnForRuns(db, runIds, repository) {
     const ids = [...new Set(runIds.filter((id) => typeof id === 'string' && id.length > 0))];
@@ -275,6 +299,13 @@ function computeDriftNudges(input) {
     }
     return nudges;
 }
+/** The derivation a Flow -> Spec delivery recorded at settle (first unit that has one). */
+function packetDerivation(row, evidence) {
+    const found = (evidence?.units ?? []).map((unit) => unit.runtime?.derivation).find((value) => Boolean(value));
+    if (found)
+        return { status: 'available', ...found };
+    return row.loop_id === loop_factory_1.FLOW_SPEC_LOOP_ID ? { status: 'unavailable' } : null;
+}
 /** Where a follow-up run's `FOLLOW-UP REPORT` can be found after settle: the
  * harvested verify tails (the final reply of record). Nothing else is guessed. */
 function followUpReportSource(evidence) {
@@ -283,7 +314,7 @@ function followUpReportSource(evidence) {
     const parts = evidence.units.flatMap((unit) => [unit.verifyTail, unit.sentinelDetail, unit.runtime?.review?.summary]).filter((v) => typeof v === 'string' && v.length > 0);
     return parts.length > 0 ? parts.join('\n') : null;
 }
-function composeReviewPacket({ db, row, repositoryId = row.repository_id ?? undefined, includeLegacyProvenance = false }) {
+function composeReviewPacket({ db, row, repositoryId = row.repository_id ?? undefined, includeLegacyProvenance = false, flowSettlement = null }) {
     const repository = repositoryId ? { repositoryId, includeLegacy: includeLegacyProvenance } : undefined;
     const ticketIds = safeParse(row.ticket_ids, []);
     const units = safeParse(row.branches, []);
@@ -382,6 +413,8 @@ function composeReviewPacket({ db, row, repositoryId = row.repository_id ?? unde
         proof: buildProof(units, evidence?.units ?? null, churn, confidence),
         watchOut: buildWatchOut(confidence, churn, variant),
         confidence,
+        whatToLookAt: (0, review_brief_1.buildWhatToLookAt)(evidence?.units ?? []),
+        riskSummary: (0, review_brief_1.summarizeReviewBriefs)((evidence?.units ?? []).map((unit) => unit.reviewBrief)),
         cost: { totalUsd: costSum?.totalUsd ?? null, estimated: costSum?.estimated ?? false },
         evidenceUnavailable: evidence === null || evidence.harvest === 'failed',
         runIds,
@@ -395,6 +428,12 @@ function composeReviewPacket({ db, row, repositoryId = row.repository_id ?? unde
         chainCostUsd: chainCosts.length > 0 ? chainCosts.reduce((sum, value) => sum + value, 0) : null,
         chainCostEstimated: versions.some((version) => version.costEstimated),
         driftNudges,
+        agentActions: agentActionsForRuns(db, runIds),
+        derivation: packetDerivation(row, evidence),
+        flowSettlement,
+        requirementsDemonstrated: (0, run_records_1.buildRequirementsDemonstrated)(evidence?.units ?? []),
+        baseline: (0, run_records_1.buildBaselineSection)(evidence?.units ?? []),
+        needsHumanEyes: evidence?.humanRules?.length ? evidence.humanRules : null,
     };
 }
 /** Assert-by-construction guard used in tests and by the route: no packet field

package/server/dist/modules/delivery/runtime/review-wip-gate.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReviewWipGate = createReviewWipGate;
+const review_wip_1 = require("../domain/review-wip");
+const review_wip_store_1 = require("../adapters/review-wip-store");
+/**
+ * Per-project review WIP admission. Bound at composition to one project's
+ * connection; the in-memory reservation count closes the window between the
+ * check and the delivery row insert, so parallel launches (Launch all, MCP
+ * launch_all) cannot overshoot the limit.
+ *
+ * Fail-open: an unreadable snapshot or setting never blocks work (mirrors the
+ * daily budget gate); the failure is logged.
+ */
+function createReviewWipGate(options) {
+    // One entry per admitted, unanswered launch (rail index). A reservation
+    // whose rail already shows its new delivery row is not counted twice.
+    const reservations = [];
+    const reservedBeyond = (pending) => reservations.filter((railIndex) => !pending.some((item) => item.railIndex === railIndex)).length;
+    const read = () => ({
+        limit: (0, review_wip_1.normalizeReviewWipLimit)(options.readLimit()),
+        pending: (0, review_wip_1.listPendingReview)((0, review_wip_store_1.readReviewWipSnapshot)(options.db)),
+    });
+    return {
+        status() {
+            try {
+                const state = read();
+                return { ...state, reserved: reservedBeyond(state.pending) };
+            }
+            catch (error) {
+                console.warn('[review-wip] state unavailable:', error instanceof Error ? error.message : error);
+                return { limit: null, pending: [], reserved: reservations.length };
+            }
+        },
+        admit(railIndex, launch) {
+            const addsWip = (0, review_wip_1.launchAddsReviewWip)(launch);
+            if (!addsWip)
+                return { ok: true, release: () => { } };
+            let state;
+            try {
+                state = read();
+            }
+            catch (error) {
+                console.warn('[review-wip] state unavailable; admitting the launch:', error instanceof Error ? error.message : error);
+                return { ok: true, release: () => { } };
+            }
+            const rejection = (0, review_wip_1.evaluateReviewWip)({ ...state, reserved: reservedBeyond(state.pending), addsWip });
+            if (rejection)
+                return { ok: false, rejection };
+            if (state.limit === null)
+                return { ok: true, release: () => { } };
+            reservations.push(railIndex);
+            let released = false;
+            return {
+                ok: true,
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    const at = reservations.indexOf(railIndex);
+                    if (at >= 0)
+                        reservations.splice(at, 1);
+                },
+            };
+        },
+    };
+}

package/server/dist/modules/delivery/runtime/run-records.js

@@ -0,0 +1,267 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASELINE_BLOCKER_CODE = exports.nodeRunRecordFs = exports.CLARIFICATIONS_FILE = exports.BASELINE_FILE = exports.SPEC_TRACE_FILE = void 0;
+exports.readRunRecordText = readRunRecordText;
+exports.parseSpecTraceReport = parseSpecTraceReport;
+exports.readSpecTrace = readSpecTrace;
+exports.parseBaselineRecord = parseBaselineRecord;
+exports.baselineCapabilities = baselineCapabilities;
+exports.readBaseline = readBaseline;
+exports.parseClarificationsRecord = parseClarificationsRecord;
+exports.readClarifications = readClarifications;
+exports.hasClarificationContent = hasClarificationContent;
+exports.buildRequirementsDemonstrated = buildRequirementsDemonstrated;
+exports.buildBaselineSection = buildBaselineSection;
+/**
+ * Core's phase-3 run records (feedback-2026-10), read at settle into the
+ * delivery evidence and rendered in the review packet:
+ *
+ *  - `spec-trace.json` (Core `specTrace: 1`, contract 5.7): which spec
+ *    requirements a passing test demonstrates ("Requirements demonstrated X/Y").
+ *  - `baseline.json` (Core `baselineOnTouch: 1`, contract 5.7): the
+ *    characterization of code no capability described ("Spec created where
+ *    the work passed").
+ *  - `clarifications.json` (Core `architectClarifications: 1`, contract 5.7):
+ *    the architect's questions, or the assumptions it proceeded on.
+ *
+ * Pure parsing apart from the injected fs seam. Tolerant: an unknown schema,
+ * a malformed entry or a missing file never throws, never invents a value and
+ * never changes any decision — every record is advisory evidence. Lists are
+ * bounded so a large report cannot bloat `settle_evidence`.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.SPEC_TRACE_FILE = 'spec-trace.json';
+exports.BASELINE_FILE = 'baseline.json';
+exports.CLARIFICATIONS_FILE = 'clarifications.json';
+const LIST_CAP = 200;
+const TEST_CAP = 5;
+const TEXT_CAP = 600;
+const FILE_CAP = 1024 * 1024;
+/** Node fs implementation of the seam. */
+exports.nodeRunRecordFs = {
+    readFile: (filePath) => fs_1.default.readFileSync(filePath, 'utf8'),
+    listDir: (dirPath) => fs_1.default.readdirSync(dirPath),
+    fileExists: (filePath) => fs_1.default.existsSync(filePath),
+    fileMtimeMs: (filePath) => fs_1.default.statSync(filePath).mtimeMs,
+};
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value, cap = TEXT_CAP) {
+    return typeof value === 'string' && value.trim() ? value.trim().slice(0, cap) : null;
+}
+function count(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+function strings(value, cap = LIST_CAP) {
+    return Array.isArray(value) ? value.flatMap((item) => { const t = text(item); return t ? [t] : []; }).slice(0, cap) : [];
+}
+/**
+ * Raw JSON text of a run record. Engine 1 writes it in the run's pipeline dir
+ * (`<pipeline>/<runId>/<file>`); an engine 2 implementation piece writes it in
+ * its own child dir (`<pipeline>/<runId[0..80]>-impl-<digest>/<file>`), so the
+ * newest such sibling is the fallback. Null when absent, oversized or unreadable.
+ */
+function readRunRecordText(runtimeDir, file, fsIo) {
+    const candidates = [path_1.default.join(runtimeDir, file)];
+    try {
+        const root = path_1.default.dirname(runtimeDir);
+        const prefix = `${path_1.default.basename(runtimeDir).slice(0, 80)}-impl-`;
+        const children = fsIo.listDir(root).filter((name) => name.startsWith(prefix)).map((name) => path_1.default.join(root, name, file))
+            .filter((candidate) => fsIo.fileExists(candidate))
+            .sort((a, b) => fsIo.fileMtimeMs(b) - fsIo.fileMtimeMs(a));
+        candidates.push(...children);
+    }
+    catch { /* no pipeline root: only the direct path */ }
+    for (const candidate of candidates) {
+        try {
+            if (!fsIo.fileExists(candidate))
+                continue;
+            const raw = fsIo.readFile(candidate);
+            if (raw.length > FILE_CAP)
+                return null;
+            return raw;
+        }
+        catch { /* try the next candidate */ }
+    }
+    return null;
+}
+function parseJson(raw) {
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function tests(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        if (!isRecord(item))
+            return [];
+        const file = text(item.file, 512);
+        return file ? [{ file, line: Number.isSafeInteger(item.line) ? item.line : null }] : [];
+    }).slice(0, TEST_CAP);
+}
+/** Parse Core's spec-trace report; null when it is not a schema-1 report. */
+function parseSpecTraceReport(value) {
+    if (!isRecord(value) || value.schemaVersion !== 1)
+        return null;
+    let omitted = 0;
+    const take = (list, parse) => {
+        if (!Array.isArray(list))
+            return [];
+        const out = [];
+        for (const item of list) {
+            const parsed = isRecord(item) ? parse(item) : null;
+            if (!parsed)
+                continue;
+            if (out.length < LIST_CAP)
+                out.push(parsed);
+            else
+                omitted++;
+        }
+        return out;
+    };
+    const demonstrated = take(value.demonstrated, (item) => {
+        const id = text(item.id, 300);
+        return id ? { id, name: text(item.name) ?? id, tests: tests(item.tests) } : null;
+    });
+    const undemonstrated = take(value.undemonstrated, (item) => {
+        const id = text(item.id, 300);
+        const reason = item.reason === 'no-test' || item.reason === 'not-executed' || item.reason === 'failed' ? item.reason : 'no-test';
+        return id ? { id, name: text(item.name) ?? id, reason: reason, tests: tests(item.tests) } : null;
+    });
+    const untagged = take(value.untagged, (item) => {
+        const tag = text(item.tag, 300), file = text(item.file, 512);
+        return tag && file ? { tag, file, line: Number.isSafeInteger(item.line) ? item.line : null } : null;
+    });
+    const evidence = value.evidence === 'receipt' || value.evidence === 'tests-passed' ? value.evidence : 'none';
+    return {
+        evidence,
+        receiptId: text(value.receiptId, 128),
+        generatedAt: text(value.generatedAt, 64),
+        changes: strings(value.changes, 20),
+        // Never report fewer requirements than the lists carry.
+        requirements: Math.max(count(value.requirements), demonstrated.length + undemonstrated.length),
+        demonstrated,
+        undemonstrated,
+        untagged,
+        touched: strings(value.touched),
+        touchedUndemonstrated: strings(value.touchedUndemonstrated),
+        omitted,
+    };
+}
+function readSpecTrace(runtimeDir, fsIo) {
+    return parseSpecTraceReport(parseJson(readRunRecordText(runtimeDir, exports.SPEC_TRACE_FILE, fsIo)));
+}
+const BASELINE_STATUSES = ['not-needed', 'planned', 'passed', 'failed', 'violated'];
+/** Parse Core's baseline record; null when it is not a schema-1 record. */
+function parseBaselineRecord(value) {
+    if (!isRecord(value) || value.schemaVersion !== 1 || !BASELINE_STATUSES.includes(value.status))
+        return null;
+    const detection = isRecord(value.detection) ? value.detection : {};
+    const testFiles = Array.isArray(value.tests)
+        ? value.tests.flatMap((item) => typeof item === 'string' ? [item] : isRecord(item) && typeof item.file === 'string' ? [item.file] : []).map((file) => file.trim().slice(0, 512)).filter(Boolean).slice(0, LIST_CAP)
+        : [];
+    return {
+        status: value.status,
+        change: text(value.change, 128),
+        recordedAt: text(value.recordedAt, 64),
+        uncovered: strings(detection.uncovered),
+        covered: Array.isArray(detection.covered) ? detection.covered.length : 0,
+        tests: testFiles,
+        receiptId: text(value.receiptId, 128),
+        reason: text(value.reason, 2000),
+        capabilities: [],
+        cost: null,
+    };
+}
+/** Requirement counts per capability of the trace's touched (as-built) requirements. */
+function baselineCapabilities(trace) {
+    if (!trace)
+        return [];
+    const demonstrated = new Set(trace.demonstrated.map((item) => item.id));
+    const byCapability = new Map();
+    for (const id of trace.touched) {
+        const capability = id.split('/')[0];
+        if (!capability)
+            continue;
+        const entry = byCapability.get(capability) ?? { requirements: 0, demonstrated: 0 };
+        entry.requirements++;
+        if (demonstrated.has(id))
+            entry.demonstrated++;
+        byCapability.set(capability, entry);
+    }
+    return [...byCapability.entries()].map(([capability, entry]) => ({ capability, ...entry }));
+}
+function readBaseline(runtimeDir, fsIo) {
+    return parseBaselineRecord(parseJson(readRunRecordText(runtimeDir, exports.BASELINE_FILE, fsIo)));
+}
+/** Core's blocker code when characterization tests fail on the unchanged code. */
+exports.BASELINE_BLOCKER_CODE = 'baseline_characterization_failed';
+function clarification(item) {
+    if (!isRecord(item))
+        return null;
+    const question = text(item.question, 2000);
+    if (!question || !['high', 'medium', 'low'].includes(item.impact))
+        return null;
+    return { question, impact: item.impact, default: text(item.default, 2000) };
+}
+/** Parse Core's clarifications record; null when it is not a schema-1 record. */
+function parseClarificationsRecord(value) {
+    if (!isRecord(value) || value.schemaVersion !== 1)
+        return null;
+    if (value.status !== 'awaiting-answers' && value.status !== 'proceeded')
+        return null;
+    const list = (input) => Array.isArray(input) ? input.map(clarification).filter((item) => item !== null).slice(0, 10) : [];
+    return {
+        change: text(value.change, 128),
+        policy: text(value.policy, 40),
+        status: value.status,
+        recordedAt: text(value.recordedAt, 64),
+        clarifications: list(value.clarifications),
+        blocking: list(value.blocking),
+        assumptions: strings(value.assumptions, 40),
+    };
+}
+function readClarifications(runtimeDir, fsIo) {
+    return parseClarificationsRecord(parseJson(readRunRecordText(runtimeDir, exports.CLARIFICATIONS_FILE, fsIo)));
+}
+/** True when the record carries something worth telling the issue's watchers. */
+function hasClarificationContent(record) {
+    return record.status === 'awaiting-answers' ? record.blocking.length > 0 || record.clarifications.length > 0 : record.assumptions.length > 0 || record.clarifications.length > 0;
+}
+function buildRequirementsDemonstrated(units) {
+    const present = units.filter((unit) => !!unit.specTrace);
+    if (present.length === 0)
+        return null;
+    const out = { demonstrated: 0, total: 0, touched: 0, touchedDemonstrated: 0, demonstratedList: [], undemonstratedList: [], untaggedList: [], withoutReceipt: false };
+    for (const { ticketId, specTrace: trace } of present) {
+        out.demonstrated += trace.demonstrated.length;
+        out.total += trace.requirements;
+        out.touched += trace.touched.length;
+        out.touchedDemonstrated += trace.touched.length - trace.touchedUndemonstrated.length;
+        if (trace.evidence !== 'receipt')
+            out.withoutReceipt = true;
+        const touched = new Set(trace.touched);
+        out.demonstratedList.push(...trace.demonstrated.map((item) => ({ ...item, ticketId })));
+        out.undemonstratedList.push(...trace.undemonstrated.map((item) => ({ id: item.id, name: item.name, reason: item.reason, touched: touched.has(item.id), ticketId })));
+        out.untaggedList.push(...trace.untagged.map((item) => ({ ...item, ticketId })));
+    }
+    // Touched requirements first: they are what this change is accountable for.
+    out.undemonstratedList.sort((a, b) => Number(b.touched) - Number(a.touched));
+    return out;
+}
+/** "Spec created where the work passed" across the delivery's units. */
+function buildBaselineSection(units) {
+    const list = units.flatMap((unit) => unit.baseline && unit.baseline.status !== 'not-needed' ? [{ ...unit.baseline, ticketId: unit.ticketId }] : []);
+    return list.length ? list : null;
+}

package/server/dist/modules/delivery/runtime/run-review-diagnosis.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRunReviewDiagnosis = readRunReviewDiagnosis;
+/**
+ * The reviewer's outcome for one run, for the operator's diagnosis tools
+ * (`specrails_jobs runtime_diagnose` / `runtime_evidence`): approved, score,
+ * bounded issues, the summary's first lines, failing host checks and — for
+ * Flow → Spec — the derivation coverage. Read through the SAME evidence path
+ * as settlement: the delivery's stored settle evidence first, else the
+ * retained run read-only (`healRuntimeEvidence` over the definition probe for
+ * engine 2, the pipeline dir for engine 1). Never throws.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
+const delivery_evidence_1 = require("./delivery-evidence");
+const flow_review_outcome_1 = require("./flow-review-outcome");
+const ISSUES_CAP = 10;
+const ISSUE_TEXT_CAP = 400;
+const SUMMARY_LINES = 5;
+const SUMMARY_CAP = 800;
+const UNEXPLAINED_CAP = 20;
+const clip = (text, cap) => (text.length <= cap ? text : `${text.slice(0, cap).trimEnd()}…`);
+function storedUnit(db, runId) {
+    const rows = db.prepare(`SELECT loop_id, implementation_outcome, settle_evidence FROM rail_pr_deliveries
+    WHERE settle_evidence IS NOT NULL AND run_ids LIKE ? ORDER BY created_at DESC LIMIT 5`).all(`%${JSON.stringify(runId)}%`);
+    for (const row of rows) {
+        const evidence = (0, delivery_evidence_1.readSettleEvidence)(row.settle_evidence);
+        const unit = evidence?.units.find((candidate) => candidate.runId === runId);
+        if (evidence && unit)
+            return { unit, loopId: row.loop_id, implementationOutcome: row.implementation_outcome, evidence };
+    }
+    return null;
+}
+function loopOf(db, runId) {
+    const row = (0, loop_runs_store_1.getLoopRun)(db, runId);
+    let reviewerStepId;
+    try {
+        reviewerStepId = (0, loop_runs_store_1.readDefinitionRun)(db, runId)?.request.graph.config.reviewerStepId;
+    }
+    catch {
+        reviewerStepId = undefined;
+    }
+    return { loopId: row?.loop_id ?? null, engineVersion: row?.engine_version ?? null, ...(reviewerStepId ? { reviewerStepId } : {}) };
+}
+function project(runtime, source, loopId, implementationOutcome, unit) {
+    const review = runtime.review;
+    const scopedReviewCount = runtime.scopedReviews?.length ?? (review ? 1 : 0);
+    // Several branch verdicts: report the latest one recorded, flagged as such.
+    const latest = review ?? runtime.scopedReviews?.[runtime.scopedReviews.length - 1]?.review ?? null;
+    const issues = latest?.issues.filter((issue) => issue.trim()) ?? [];
+    const derivation = runtime.derivation ?? (runtime.derivationPath ? (0, delivery_evidence_1.readDerivationFile)(runtime.derivationPath, { fileExists: node_fs_1.default.existsSync, readFile: (file) => node_fs_1.default.readFileSync(file, 'utf8') }) : null);
+    const flowSpec = loopId === flow_review_outcome_1.FLOW_SPEC_DELIVERY_LOOP_ID;
+    const flow = flowSpec ? (0, flow_review_outcome_1.flowReviewOutcome)({ loopId, implementationOutcome: implementationOutcome ?? 'failed', evidence: { schemaVersion: 1, harvest: 'ok', harvestedAt: '', units: [{ ...unit, runtime }] } }) : null;
+    return {
+        source,
+        review: latest ? {
+            approved: latest.approved,
+            score: latest.score,
+            issues: issues.slice(0, ISSUES_CAP).map((issue) => clip(issue.trim(), ISSUE_TEXT_CAP)),
+            issuesOmitted: Math.max(0, issues.length - ISSUES_CAP),
+            summary: latest.summary ? clip(latest.summary.split(/\r?\n/).filter((line) => line.trim()).slice(0, SUMMARY_LINES).join('\n'), SUMMARY_CAP) : null,
+            scopedReviewCount,
+        } : null,
+        failingChecks: runtime.commands
+            .filter((command) => command.outcome === 'failed' || (command.exitCode !== null && command.exitCode !== 0))
+            .slice(0, 10)
+            .map((command) => ({ command: clip(command.label, 200), exitCode: command.exitCode })),
+        derivation: flowSpec && derivation ? {
+            change: derivation.change, files: derivation.files, explained: derivation.explained,
+            unexplainedFiles: derivation.unexplainedFiles.slice(0, UNEXPLAINED_CAP),
+            unexplainedOmitted: derivation.unexplainedOmitted + Math.max(0, derivation.unexplainedFiles.length - UNEXPLAINED_CAP),
+            confidence: derivation.confidence,
+        } : null,
+        flowOutcome: flow?.reason ?? null,
+    };
+}
+/** The reviewer outcome of `runId`; null when no source carries runtime evidence. */
+async function readRunReviewDiagnosis(deps) {
+    try {
+        const run = loopOf(deps.db, deps.runId);
+        const stored = storedUnit(deps.db, deps.runId);
+        if (stored?.unit.runtime?.review)
+            return project(stored.unit.runtime, 'settle-evidence', stored.loopId ?? run.loopId, stored.implementationOutcome, stored.unit);
+        const unit = { ticketId: stored?.unit.ticketId ?? 0, runId: deps.runId, sentinel: 'absent', sentinelDetail: null, verifyTail: null, confidence: null,
+            ...(stored?.unit.reviewerStepId ?? run.reviewerStepId ? { reviewerStepId: stored?.unit.reviewerStepId ?? run.reviewerStepId } : {}) };
+        const statuses = run.engineVersion === 2 ? await deps.probe([deps.runId]) : new Map();
+        const healed = (0, delivery_evidence_1.healRuntimeEvidence)({ schemaVersion: 1, harvest: 'ok', harvestedAt: new Date().toISOString(), units: [unit] }, deps.pipelineDir, {}, statuses);
+        const runtime = healed?.units[0]?.runtime;
+        if (runtime)
+            return project(runtime, 'retained-run', stored?.loopId ?? run.loopId, stored?.implementationOutcome ?? null, unit);
+        // The retained run is gone: whatever the settle evidence kept is still the best answer.
+        if (stored?.unit.runtime)
+            return project(stored.unit.runtime, 'settle-evidence', stored.loopId ?? run.loopId, stored.implementationOutcome, stored.unit);
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/server/dist/modules/execution/adapters/budget-storage.js

@@ -1,6 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESKTOP_CAP_KEYS = exports.PROJECT_CAP_KEYS = void 0;
+exports.readProjectCaps = readProjectCaps;
+exports.readDesktopCaps = readDesktopCaps;
+exports.writeProjectCap = writeProjectCap;
+exports.projectSpendSince = projectSpendSince;
+exports.projectDailySpend = projectDailySpend;
 exports.createQueueBudgetStorage = createQueueBudgetStorage;
+const spend_caps_1 = require("../domain/spend-caps");
+/** `queue_state` keys of the project's caps (the daily one predates caps). */
+exports.PROJECT_CAP_KEYS = {
+    day: 'config.daily_budget_usd',
+    week: 'config.weekly_budget_usd',
+    month: 'config.monthly_budget_usd',
+    run: 'config.run_cap_usd',
+};
+/** `desktop_settings` keys of the app-wide caps (the daily one predates caps). */
+exports.DESKTOP_CAP_KEYS = {
+    day: 'desktop_daily_budget_usd',
+    week: 'desktop_weekly_budget_usd',
+    month: 'desktop_monthly_budget_usd',
+    run: 'desktop_run_cap_usd',
+};
+const positive = (raw) => {
+    if (raw === undefined)
+        return null;
+    const value = parseFloat(raw);
+    return value > 0 ? value : null;
+};
+/** The project's configured caps; unset, zero or unparseable ⇒ null (no cap). */
+function readProjectCaps(db) {
+    const read = (key) => positive(db.prepare('SELECT value FROM queue_state WHERE key = ?').get(exports.PROJECT_CAP_KEYS[key])?.value);
+    return { day: read('day'), week: read('week'), month: read('month'), run: read('run') };
+}
+/** The app-wide caps from a `desktop_settings` getter (`getDesktopSetting` bound to the desktop DB). */
+function readDesktopCaps(get) {
+    const read = (key) => positive(get(key) ?? undefined);
+    return { day: read(exports.DESKTOP_CAP_KEYS.day), week: read(exports.DESKTOP_CAP_KEYS.week), month: read(exports.DESKTOP_CAP_KEYS.month), run: read(exports.DESKTOP_CAP_KEYS.run) };
+}
+/** Set (number > 0) or clear (null) one project cap. */
+function writeProjectCap(db, key, value) {
+    if (value === null)
+        db.prepare('DELETE FROM queue_state WHERE key = ?').run(exports.PROJECT_CAP_KEYS[key]);
+    else
+        db.prepare('INSERT OR REPLACE INTO queue_state (key, value) VALUES (?, ?)').run(exports.PROJECT_CAP_KEYS[key], String(value));
+}
+/**
+ * Provider-reported spend of one project since `sinceIso` (rows without a cost
+ * are NOT zero — they are skipped, like the daily budget has always done).
+ */
+function projectSpendSince(db, projectId, sinceIso) {
+    return db.prepare(`SELECT COALESCE(SUM(total_cost_usd), 0) as total FROM ai_invocations
+         WHERE project_id = ? AND total_cost_usd IS NOT NULL AND started_at >= ?`).get(projectId, sinceIso).total;
+}
+/** Spend of one project grouped by LOCAL calendar day (cents), for the projection. */
+function projectDailySpend(db, projectId, sinceIso) {
+    const rows = db.prepare(`SELECT started_at, total_cost_usd FROM ai_invocations
+         WHERE project_id = ? AND total_cost_usd IS NOT NULL AND started_at >= ?`).all(projectId, sinceIso);
+    const byDay = new Map();
+    for (const row of rows) {
+        const at = new Date(row.started_at);
+        if (Number.isNaN(at.getTime()))
+            continue;
+        const key = (0, spend_caps_1.localDayKey)(at);
+        byDay.set(key, (byDay.get(key) ?? 0) + row.total_cost_usd);
+    }
+    // Round once per day: rounding every row would zero out many small calls.
+    return [...byDay].map(([day, usd]) => ({ day, cents: (0, spend_caps_1.toCents)(usd) }));
+}
 function createQueueBudgetStorage(db) {
     return {
         project(projectId, dayStart) {
@@ -14,6 +81,15 @@ function createQueueBudgetStorage(db) {
              WHERE project_id = ? AND total_cost_usd IS NOT NULL AND started_at >= ?`).get(projectId, dayStart());
             return { budget, totalSpend: spend.total };
         },
+        /** A project's weekly/monthly cap with its spend since the period start. */
+        projectPeriod(projectId, period, periodStart) {
+            if (!projectId)
+                return null;
+            const budget = readProjectCaps(db)[period];
+            if (budget === null)
+                return null;
+            return { budget, totalSpend: projectSpendSince(db, projectId, periodStart()) };
+        },
         pause() {
             db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('paused', 'true')`).run();
         },

package/server/dist/modules/execution/application/enforce-budget.js

@@ -1,14 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enforceDailyBudgets = enforceDailyBudgets;
+exports.evaluateDailyBudgets = evaluateDailyBudgets;
+const daily_budget_1 = require("../domain/daily-budget");
 /** Project admission is evaluated first; storage failures abort later effects. */
 function enforceDailyBudgets(ports) {
     const enforce = (scope, snapshot) => {
-        if (snapshot?.budget != null && snapshot.budget > 0 && snapshot.totalSpend >= snapshot.budget) {
+        if ((0, daily_budget_1.isDailyBudgetExceeded)(snapshot))
             ports.exceeded(scope, { ...snapshot, budget: snapshot.budget });
-        }
     };
     enforce('project', ports.project());
     if (ports.desktop)
         enforce('desktop', ports.desktop());
 }
+/**
+ * Read-only admission check for cost-incurring launches: the same budgets and
+ * the same predicate as {@link enforceDailyBudgets}, without pausing anything.
+ * The project budget wins when both are exceeded (it is the narrower cap).
+ */
+function evaluateDailyBudgets(ports) {
+    const project = ports.project();
+    if ((0, daily_budget_1.isDailyBudgetExceeded)(project))
+        return { scope: 'project', budget: project.budget, totalSpend: project.totalSpend };
+    const desktop = ports.desktop?.() ?? null;
+    if ((0, daily_budget_1.isDailyBudgetExceeded)(desktop))
+        return { scope: 'desktop', budget: desktop.budget, totalSpend: desktop.totalSpend };
+    return null;
+}