specrails-desktop 2.20.1 → 2.22.0

package/server/dist/db.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ULTRACODE_PRE_PROMPT = void 0;
 exports.initDb = initDb;
 exports.createJob = createJob;
+exports.markJobInteractive = markJobInteractive;
 exports.accumulateInteractiveTurn = accumulateInteractiveTurn;
 exports.finalizeInteractiveJob = finalizeInteractiveJob;
 exports.finishJob = finishJob;
@@ -719,6 +720,87 @@ const MIGRATIONS = [
       CREATE INDEX IF NOT EXISTS idx_rail_worktrees_rail ON rail_worktrees(rail_index);
     `);
     },
+    // Migration 36: rail_pr_deliveries — one row per isolated rail LAUNCH tracking
+    // the ask-first PR decision lifecycle (building → on_review → pr_draft →
+    // pr_ready → merged | discarded | pr_failed). The durable single source of
+    // truth both decision surfaces (rail row + agent chat) read and write, so a
+    // refresh/restart never loses a pending PR decision. `branches` captures the
+    // per-unit DeliverBranch records at build-settle (deferred deliverRailAsPr
+    // cannot be reconstructed without them); `worktree_ids` links the
+    // rail_worktrees ledger rows for discard cleanup. Additive + idempotent.
+    (db) => {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS rail_pr_deliveries (
+        id                     TEXT PRIMARY KEY,
+        rail_index             INTEGER NOT NULL,
+        loop_id                TEXT,
+        rail_key               TEXT NOT NULL,
+        ticket_ids             TEXT NOT NULL,
+        base_branch            TEXT NOT NULL,
+        branch                 TEXT,
+        pr_url                 TEXT,
+        pr_number              INTEGER,
+        pr_state               TEXT NOT NULL DEFAULT 'none',
+        decision               TEXT NOT NULL DEFAULT 'building',
+        branches               TEXT NOT NULL DEFAULT '[]',
+        loop_name              TEXT NOT NULL DEFAULT '',
+        worktree_ids           TEXT NOT NULL DEFAULT '[]',
+        origin_surface         TEXT NOT NULL DEFAULT 'dashboard',
+        origin_conversation_id TEXT,
+        created_at             TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at             TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_rail_pr_deliveries_rail ON rail_pr_deliveries(rail_index);
+      CREATE INDEX IF NOT EXISTS idx_rail_pr_deliveries_active ON rail_pr_deliveries(decision);
+    `);
+    },
+    // Migration 37: file_story_contributions — per-intervention "construction
+    // story" data for the Code/Files explorer. One row per file_provenance row
+    // that had a collectable patch: line stats (added/removed), a ~4KB patch
+    // excerpt (the full patch stays in file_provenance_diffs), and a nullable
+    // plain-language AI `summary` of what that spec contributed to the file
+    // (generated on demand, budget-gated — see file-story-manager.ts). Written
+    // inside recordProvenanceForJob's transaction so EVERY provenance producer
+    // (queue-manager jobs AND the loop-run seam) gets stats for free. Additive.
+    (db) => {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS file_story_contributions (
+        provenance_id        INTEGER PRIMARY KEY,
+        job_id               TEXT,
+        file_path            TEXT NOT NULL,
+        added_lines          INTEGER NOT NULL DEFAULT 0,
+        removed_lines        INTEGER NOT NULL DEFAULT 0,
+        patch_excerpt        TEXT,
+        summary              TEXT,
+        summary_model        TEXT,
+        summary_generated_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_file_story_contributions_path ON file_story_contributions(file_path);
+    `);
+    },
+    // Migration 38: rail_pr_deliveries.run_ids — JSON string[] of the loop-run
+    // ids an isolated rail launch fanned out (order matches ticket order; a
+    // scope='all' launch has exactly one). Persisted right after allocation so
+    // the PR decision surfaces (agent-chat card + dashboard strip) can render a
+    // per-run "View log" chip with live vitals that survives refresh/restart.
+    // Additive + idempotent (guarded by PRAGMA table_info, mirroring 18–36).
+    (db) => {
+        const cols = db.prepare(`PRAGMA table_info(rail_pr_deliveries)`).all().map((r) => r.name);
+        if (!cols.includes('run_ids')) {
+            db.exec(`ALTER TABLE rail_pr_deliveries ADD COLUMN run_ids TEXT NOT NULL DEFAULT '[]'`);
+        }
+    },
+    // Migration 39: seed the three BASE rails (indices 0-2) into rail_meta.
+    // Dynamic rails make rail_meta the EXISTENCE authority (a rail exists iff it
+    // has a rail_meta identity row or leftover ticket rows) — seeding once here,
+    // instead of re-seeding on every read, lets a user genuinely delete a base
+    // rail (the router still guards: never the last one, never a non-empty or
+    // active one). INSERT OR IGNORE keeps any existing renamed-rail rows intact.
+    (db) => {
+        db.exec(`
+      INSERT OR IGNORE INTO rail_meta (rail_index, name) VALUES (0, NULL), (1, NULL), (2, NULL);
+    `);
+    },
 ];
 function applyMigrations(db) {
     // Ensure the migrations table exists (migration 1 creates it, but we need
@@ -783,6 +865,16 @@ function createJob(db, job) {
     db.prepare('INSERT OR IGNORE INTO jobs (id, command, started_at, status, priority, depends_on_job_id, pipeline_id, interactive) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(job.id, job.command, job.started_at, 'running', job.priority ?? 'normal', job.depends_on_job_id ?? null, job.pipeline_id ?? null, job.interactive ? 1 : 0);
     db.prepare('UPDATE jobs SET status = ?, started_at = ?, interactive = ? WHERE id = ?').run('running', job.started_at, job.interactive ? 1 : 0, job.id);
 }
+/**
+ * Flip a job row's `interactive` flag AFTER creation. Used by the loop engine
+ * when an ai-step upgrades the run's backing job to a resident interactive
+ * session — the row was created at run start (before the step's provider
+ * capability/kill-switch gate is consulted), so the flag lands lazily at the
+ * first interactive step spawn. Idempotent.
+ */
+function markJobInteractive(db, jobId) {
+    db.prepare('UPDATE jobs SET interactive = 1 WHERE id = ?').run(jobId);
+}
 /**
  * Add one completed interactive turn's REAL usage into the job row. Token/cost/
  * turn columns accumulate (COALESCE so the first turn starts from a clean base);
@@ -1151,11 +1243,13 @@ function getProjectSettings(db) {
     const modelRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.orchestrator_model'`).get();
     const prePromptRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.pre_prompt'`).get();
     const ultraPrePromptRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.ultracode_pre_prompt'`).get();
+    const integrationBranchRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.integration_branch'`).get();
     return {
         pipelineTelemetryEnabled: telemetryRow?.value === 'true',
         orchestratorModel: modelRow?.value ?? 'sonnet',
         prePrompt: prePromptRow?.value ?? '',
         ultraPrePrompt: ultraPrePromptRow?.value ?? '',
+        integrationBranch: integrationBranchRow?.value ?? '',
     };
 }
 /** Resolve the effective Ultracode pre-prompt: the per-project override when
@@ -1187,6 +1281,14 @@ function updateProjectSettings(db, patch) {
             db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.ultracode_pre_prompt', ?)`).run(patch.ultraPrePrompt);
         }
     }
+    if (patch.integrationBranch !== undefined) {
+        if (patch.integrationBranch.trim() === '') {
+            db.prepare(`DELETE FROM queue_state WHERE key = 'config.integration_branch'`).run();
+        }
+        else {
+            db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.integration_branch', ?)`).run(patch.integrationBranch.trim());
+        }
+    }
 }
 // ─── Explore Spec acceleration ────────────────────────────────────────────────
 /**

package/server/dist/file-provenance.js

@@ -3,11 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GIT_EXEC_ENV = void 0;
+exports.STORY_EXCERPT_MAX_BYTES = exports.GIT_EXEC_ENV = void 0;
 exports.resolveHeadSha = resolveHeadSha;
 exports.listUntracked = listUntracked;
 exports.snapshotWorkingTree = snapshotWorkingTree;
 exports.diffAgainstSnapshot = diffAgainstSnapshot;
+exports.computeDiffStats = computeDiffStats;
+exports.excerptPatch = excerptPatch;
 exports.collectDiffPatches = collectDiffPatches;
 exports.recordProvenanceForJob = recordProvenanceForJob;
 exports.getProvenanceDiff = getProvenanceDiff;
@@ -204,6 +206,37 @@ function diffAgainstSnapshot(cwd, snapshotRef, untrackedBefore, baseSha) {
     }
     return entries;
 }
+/** Upper bound on the patch excerpt stored per intervention in
+ *  file_story_contributions (the full patch stays in file_provenance_diffs). */
+exports.STORY_EXCERPT_MAX_BYTES = 4096;
+/** Count added/removed lines in a unified diff. Skips the `+++`/`---` file
+ *  headers and the `\ No newline` marker so stats reflect content lines only. */
+function computeDiffStats(patch) {
+    let added = 0;
+    let removed = 0;
+    for (const line of patch.split('\n')) {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            continue;
+        if (line.startsWith('+'))
+            added += 1;
+        else if (line.startsWith('-'))
+            removed += 1;
+    }
+    return { added, removed };
+}
+/** Cap a patch to STORY_EXCERPT_MAX_BYTES on a line boundary. */
+function excerptPatch(patch, capBytes = exports.STORY_EXCERPT_MAX_BYTES) {
+    if (Buffer.byteLength(patch, 'utf8') <= capBytes)
+        return patch;
+    let out = '';
+    for (const line of patch.split('\n')) {
+        const candidate = out.length > 0 ? `${out}\n${line}` : line;
+        if (Buffer.byteLength(candidate, 'utf8') > capBytes)
+            break;
+        out = candidate;
+    }
+    return `${out}\n[specrails-desktop] excerpt truncated\n`;
+}
 function truncatePatch(patch) {
     const bytes = Buffer.byteLength(patch, 'utf8');
     if (bytes <= MAX_PATCH_BYTES)
@@ -325,6 +358,22 @@ function recordProvenanceForJob(db, projectId, jobId, ticketId, diff, atMs = Dat
     catch {
         insertPatch = null;
     }
+    // Construction-story stats (migration 37): one row per provenance row that had
+    // a collectable patch — added/removed line counts + a ~4KB excerpt. Written in
+    // the SAME transaction so every provenance producer (queue-manager jobs and
+    // the loop-run seam in file-story.ts) records stats with no extra call. The
+    // prepare is guarded like insertPatch so a pre-migration DB degrades cleanly.
+    let insertContribution = null;
+    try {
+        insertContribution = db.prepare(`
+      INSERT OR REPLACE INTO file_story_contributions
+        (provenance_id, job_id, file_path, added_lines, removed_lines, patch_excerpt)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    }
+    catch {
+        insertContribution = null;
+    }
     const inserted = [];
     const tx = db.transaction((rows) => {
         for (const r of rows) {
@@ -341,6 +390,10 @@ function recordProvenanceForJob(db, projectId, jobId, ticketId, diff, atMs = Dat
             if (insertPatch && storedPatch) {
                 insertPatch.run(Number(result.lastInsertRowid), storedPatch.patch, storedPatch.truncated ? 1 : 0);
             }
+            if (insertContribution && storedPatch) {
+                const stats = computeDiffStats(storedPatch.patch);
+                insertContribution.run(Number(result.lastInsertRowid), jobId, r.file_path, stats.added, stats.removed, excerptPatch(storedPatch.patch));
+            }
         }
     });
     tx(pending);

package/server/dist/file-story-manager.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileStoryManager = exports.STORY_SUMMARY_MAX_LENGTH = void 0;
+exports.buildStorySystemPrompt = buildStorySystemPrompt;
+/**
+ * FileStoryManager — on-demand, budget-gated generation of the plain-language
+ * "what this spec contributed to this file" paragraph shown on each card of
+ * the Code/Files construction story.
+ *
+ * Mirrors FileSummaryManager's cost discipline: the SAME monthly budget
+ * setting (`summary_monthly_budget_usd`) and the SAME ai_invocations surface
+ * (`'file-summary'`) — one budget covers the whole Code-section AI spend and
+ * analytics need no new surface. Generation is user-initiated (per-card
+ * "Explain" button), in-flight-deduped per provenanceId, and persists to
+ * `file_story_contributions.summary` (see file-story.ts / migration 37).
+ */
+const crypto_1 = require("crypto");
+const ai_invocations_1 = require("./ai-invocations");
+const file_story_1 = require("./file-story");
+const STORY_PROMPT_EN = 'You are telling a non-developer how one part of an app was built. Below is one change made to a file: ' +
+    'the goal it implemented (a spec title) and the code changes (a diff). Write 1 to 3 sentences in plain ' +
+    'language describing what this specific change contributed to this file. No code, no jargon, no lists. ' +
+    'Output only the explanation, nothing else.';
+const STORY_PROMPT_ES = 'Estás contando a una persona no desarrolladora cómo se construyó una parte de una app. Abajo hay un cambio ' +
+    'hecho a un archivo: el objetivo que implementó (el título de una spec) y los cambios de código (un diff). ' +
+    'Escribe entre 1 y 3 frases en lenguaje llano describiendo qué aportó este cambio concreto a este archivo. ' +
+    'Sin código, sin jerga, sin listas. Devuelve solo la explicación, nada más.';
+function buildStorySystemPrompt(language) {
+    return language === 'es' ? STORY_PROMPT_ES : STORY_PROMPT_EN;
+}
+/** Bound on the generated paragraph (defensive, mirrors SUMMARY_MAX_LENGTH scale). */
+exports.STORY_SUMMARY_MAX_LENGTH = 2000;
+/** Bound on the diff excerpt fed to the model. */
+const PROMPT_PATCH_MAX_CHARS = 12000;
+class FileStoryManager {
+    deps;
+    /** In-flight dedupe: a second Explain for the same intervention rides the first. */
+    inFlight = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    explain(req) {
+        const existing = this.inFlight.get(req.provenanceId);
+        if (existing)
+            return existing;
+        // Synchronous gates run BEFORE registering in-flight so a skip result is
+        // never cached in the dedupe map (a budget skip followed immediately by an
+        // override retry must not ride the stale skipped promise).
+        //
+        // Resolve the intervention: the provenance row must exist AND belong to
+        // the requested path (the router already guarded the path; this pins the id).
+        const prov = this._loadProvenance(req.provenanceId);
+        if (!prov || prov.file_path !== req.relPath)
+            return Promise.resolve('skipped:not-found');
+        // Budget gate — same monthly cap as file summaries; explicit override only.
+        if (!req.overrideBudget) {
+            const spend = this.deps.monthToDateSpend(req.projectId);
+            if (spend >= this.deps.monthlyBudgetUsd())
+                return Promise.resolve('skipped:budget');
+        }
+        const p = this._explainInner(req, prov);
+        this.inFlight.set(req.provenanceId, p);
+        void p.catch(() => undefined).finally(() => {
+            if (this.inFlight.get(req.provenanceId) === p)
+                this.inFlight.delete(req.provenanceId);
+        });
+        return p;
+    }
+    async _explainInner(req, prov) {
+        const startedIso = new Date((this.deps.now ?? Date.now)()).toISOString();
+        const lang = this.deps.language?.() ?? 'en';
+        // Compose the change description: spec title (live lookup, tolerant) +
+        // kind + the stored patch (full patch preferred, excerpt fallback,
+        // honest note when neither survived).
+        let ticketTitle = null;
+        if (prov.ticket_id != null) {
+            try {
+                ticketTitle = this.deps.getTicketSpec?.(prov.ticket_id)?.title ?? null;
+            }
+            catch {
+                ticketTitle = null;
+            }
+        }
+        const patch = this._loadPatch(req.provenanceId);
+        const parts = [];
+        parts.push(`Spec: ${ticketTitle ?? (prov.ticket_id != null ? `#${prov.ticket_id}` : 'unknown')}`);
+        parts.push(`Change kind: ${prov.kind}`);
+        parts.push(patch ? `Diff:\n${patch.slice(0, PROMPT_PATCH_MAX_CHARS)}` : 'Diff: (not stored for this change)');
+        try {
+            const out = await this.deps.generate({
+                relPath: req.relPath,
+                contents: parts.join('\n\n'),
+                truncated: (patch?.length ?? 0) > PROMPT_PATCH_MAX_CHARS,
+                language: lang,
+            });
+            const bounded = out.summary.length > exports.STORY_SUMMARY_MAX_LENGTH
+                ? out.summary.slice(0, exports.STORY_SUMMARY_MAX_LENGTH)
+                : out.summary;
+            const persisted = (0, file_story_1.setContributionSummary)(this.deps.db, req.provenanceId, bounded, out.model, new Date((this.deps.now ?? Date.now)()).toISOString());
+            this._recordInvocation(req, startedIso, 'success', out);
+            this.deps.broadcast(this._storyMsg(req, persisted, persisted ? undefined : 'persist-failed'));
+            this.deps.broadcast({ type: 'spending.invalidated', projectId: req.projectId });
+            return persisted ? 'generated' : 'failed';
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            // Carry any partial usage the generator captured (mirrors FileSummaryManager).
+            const partial = err.partial;
+            this._recordInvocation(req, startedIso, 'failed', partial);
+            this.deps.broadcast(this._storyMsg(req, false, reason));
+            return 'failed';
+        }
+    }
+    _storyMsg(req, ok, reason) {
+        return {
+            type: 'file.story_updated',
+            projectId: req.projectId,
+            path: req.relPath,
+            provenanceId: req.provenanceId,
+            ok,
+            ...(reason ? { reason } : {}),
+        };
+    }
+    _loadProvenance(provenanceId) {
+        try {
+            const row = this.deps.db.prepare(`SELECT id, file_path, ticket_id, job_id, kind FROM file_provenance WHERE id = ?`).get(provenanceId);
+            return row ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    _loadPatch(provenanceId) {
+        try {
+            const row = this.deps.db.prepare(`SELECT patch FROM file_provenance_diffs WHERE provenance_id = ?`).get(provenanceId);
+            if (row?.patch)
+                return row.patch;
+        }
+        catch { /* fall through to excerpt */ }
+        return (0, file_story_1.getContribution)(this.deps.db, provenanceId)?.patch_excerpt ?? null;
+    }
+    _recordInvocation(req, startedIso, status, out) {
+        try {
+            (0, ai_invocations_1.recordInvocation)(this.deps.db, {
+                id: (0, crypto_1.randomUUID)(),
+                project_id: req.projectId,
+                provider: out?.provider ?? this.deps.providerId?.() ?? 'claude',
+                surface: 'file-summary',
+                surface_ref_id: null,
+                ticket_id: this._loadProvenance(req.provenanceId)?.ticket_id ?? null,
+                status,
+                started_at: startedIso,
+                finished_at: new Date((this.deps.now ?? Date.now)()).toISOString(),
+                model: out?.model,
+                total_cost_usd: out?.costUsd ?? 0,
+                tokens_in: out?.tokensIn ?? 0,
+                tokens_out: out?.tokensOut ?? 0,
+                tokens_cache_read: out?.tokensCacheRead,
+                tokens_cache_create: out?.tokensCacheCreate,
+                duration_ms: out?.durationMs ?? 0,
+                num_turns: 1,
+                total_cost_usd_estimated: !!out?.costEstimated,
+            });
+        }
+        catch (err) {
+            console.error('[file-story] recordInvocation failed:', err);
+        }
+    }
+}
+exports.FileStoryManager = FileStoryManager;

package/server/dist/file-story.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordLoopRunProvenance = recordLoopRunProvenance;
+exports.getContribution = getContribution;
+exports.setContributionSummary = setContributionSummary;
+exports.getFileStory = getFileStory;
+const feature_flags_1 = require("./feature-flags");
+const file_provenance_1 = require("./file-provenance");
+/** Warn threshold mirroring queue-manager's `provenance.large_job`. */
+const LARGE_RUN_WARN_FILES = 50;
+/**
+ * Record Code-Explorer provenance for a settled loop run. Single chokepoint:
+ * gated by the code-explorer flag, never throws (a provenance failure must
+ * never break a rail settle). Returns the number of provenance rows written.
+ */
+function recordLoopRunProvenance(input, io = {}) {
+    if (!(0, feature_flags_1.isCodeExplorerEnabled)())
+        return 0;
+    if (!input.snapshot)
+        return 0;
+    const diffFn = io.diff ?? file_provenance_1.diffAgainstSnapshot;
+    const patchesFn = io.patches ?? file_provenance_1.collectDiffPatches;
+    try {
+        const ref = input.snapshot.ref;
+        const diff = diffFn(input.repoDir, ref, input.snapshot.untracked, input.snapshot.headSha);
+        if (diff.length === 0)
+            return 0;
+        const patches = patchesFn(input.repoDir, ref, diff, input.snapshot.headSha);
+        if (diff.length > LARGE_RUN_WARN_FILES) {
+            console.warn(`[provenance.large_job] job=${input.runId} files=${diff.length}`);
+        }
+        const rows = (0, file_provenance_1.recordProvenanceForJob)(input.db, input.projectId, input.runId, input.ticketId, diff, Date.now(), patches);
+        for (const row of rows) {
+            try {
+                (0, file_provenance_1.broadcastProvenanceUpdated)(input.broadcast, input.projectId, row);
+            }
+            catch { /* non-fatal */ }
+        }
+        return rows.length;
+    }
+    catch (err) {
+        console.warn(`[file-story] loop-run provenance recording failed: ${err.message}`);
+        return 0;
+    }
+}
+/** Read one contribution row by provenance id (null when absent / pre-37 DB). */
+function getContribution(db, provenanceId) {
+    try {
+        const row = db.prepare(`SELECT provenance_id, job_id, file_path, added_lines, removed_lines,
+              patch_excerpt, summary, summary_model, summary_generated_at
+       FROM file_story_contributions WHERE provenance_id = ?`).get(provenanceId);
+        return row ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the AI-generated contribution paragraph for one intervention.
+ *  Inserts the row when the intervention pre-dates migration 37 / had no patch. */
+function setContributionSummary(db, provenanceId, summary, model, generatedAtIso = new Date().toISOString()) {
+    try {
+        const updated = db.prepare(`UPDATE file_story_contributions
+       SET summary = ?, summary_model = ?, summary_generated_at = ?
+       WHERE provenance_id = ?`).run(summary, model, generatedAtIso, provenanceId);
+        if (updated.changes > 0)
+            return true;
+        // No stats row yet (historical touch without a stored patch) — create one
+        // carrying only the summary, keyed off the provenance row's identity.
+        const prov = db.prepare(`SELECT id, file_path, job_id FROM file_provenance WHERE id = ?`).get(provenanceId);
+        if (!prov)
+            return false;
+        db.prepare(`INSERT OR REPLACE INTO file_story_contributions
+         (provenance_id, job_id, file_path, added_lines, removed_lines, patch_excerpt, summary, summary_model, summary_generated_at)
+       VALUES (?, ?, ?, 0, 0, NULL, ?, ?, ?)`).run(provenanceId, prov.job_id, prov.file_path, summary, model, generatedAtIso);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Assemble the chronological construction story for one file: every
+ * intervention (oldest first — a construction story reads forward in time),
+ * each carrying diff stats + the AI contribution when available, enriched
+ * with the spec's live title/status. Ticket lookups are failure-tolerant.
+ */
+function getFileStory(db, filePath, getTicketSpec) {
+    let rows;
+    try {
+        rows = db.prepare(`SELECT p.id, p.file_path, p.ticket_id, p.job_id, p.kind, p.at,
+              c.added_lines, c.removed_lines, c.patch_excerpt,
+              c.summary, c.summary_model, c.summary_generated_at,
+              (SELECT COUNT(*) FROM file_provenance_diffs d WHERE d.provenance_id = p.id) AS patch_count
+       FROM file_provenance p
+       LEFT JOIN file_story_contributions c ON c.provenance_id = p.id
+       WHERE p.file_path = ?
+       ORDER BY p.at ASC, p.id ASC`).all(filePath);
+    }
+    catch {
+        // Pre-migration-37 DB — degrade to the bare provenance rows (honest
+        // fallback story: kind + date + spec only).
+        rows = db.prepare(`SELECT id, ticket_id, job_id, kind, at FROM file_provenance WHERE file_path = ? ORDER BY at ASC, id ASC`).all(filePath).map((r) => ({
+            ...r,
+            added_lines: null,
+            removed_lines: null,
+            patch_excerpt: null,
+            summary: null,
+            summary_model: null,
+            summary_generated_at: null,
+            patch_count: 0,
+        }));
+    }
+    const ticketCache = new Map();
+    const resolveTicket = (ticketId) => {
+        if (ticketId == null)
+            return null;
+        if (ticketCache.has(ticketId))
+            return ticketCache.get(ticketId);
+        let resolved = null;
+        try {
+            const spec = getTicketSpec?.(ticketId);
+            if (spec) {
+                resolved = {
+                    id: ticketId,
+                    title: typeof spec.title === 'string' ? spec.title : null,
+                    status: typeof spec.status === 'string' ? spec.status : null,
+                };
+            }
+        }
+        catch { /* deleted ticket / unreadable store — degrade to null */ }
+        ticketCache.set(ticketId, resolved);
+        return resolved;
+    };
+    return rows.map((r) => ({
+        provenanceId: r.id,
+        jobId: r.job_id,
+        ticketId: r.ticket_id,
+        kind: r.kind,
+        at: r.at,
+        addedLines: r.added_lines,
+        removedLines: r.removed_lines,
+        hasPatch: r.patch_count > 0,
+        summary: r.summary,
+        summaryModel: r.summary_model,
+        summaryGeneratedAt: r.summary_generated_at,
+        ticket: resolveTicket(r.ticket_id),
+    }));
+}

package/server/dist/file-summary-generator.js

@@ -20,12 +20,12 @@ function buildSystemPrompt(language) {
 /** Compose the single user-message body that goes to the model. The provider
  *  adapter decides whether the system prompt rides along via a flag or gets
  *  folded into this string (see `adapter.capabilities.systemPromptArg`). */
-function buildUserPrompt(input, adapter) {
+function buildUserPrompt(input, adapter, systemPromptFor) {
     const body = `${input.relPath}\n${input.contents}`;
     if (adapter.capabilities.systemPromptArg)
         return body;
     // Provider does not accept a system-prompt flag; fold the instruction inline.
-    return `${buildSystemPrompt(input.language)}\n\n${body}`;
+    return `${systemPromptFor(input.language)}\n\n${body}`;
 }
 /** Cheapest model per provider for summary generation. Codex MUST run
  *  `gpt-5.4-mini` (product decision: file summaries are non-critical and the
@@ -49,13 +49,14 @@ function createFileSummaryGenerator(opts) {
     const model = opts.model ?? defaultModelFor(adapter);
     const timeoutMs = opts.timeoutMs ?? GENERATE_TIMEOUT_MS;
     const spawn = opts.spawn ?? cli_prompt_1.spawnAiCli;
+    const systemPromptFor = opts.systemPrompt ?? buildSystemPrompt;
     return async function generate(input, signal) {
         const startedAt = Date.now();
         if (signal?.aborted)
             throw new Error('file-summary generator aborted before start');
         const args = adapter.buildArgs('spec-gen', {
-            prompt: buildUserPrompt(input, adapter),
-            systemPrompt: adapter.capabilities.systemPromptArg ? buildSystemPrompt(input.language) : undefined,
+            prompt: buildUserPrompt(input, adapter, systemPromptFor),
+            systemPrompt: adapter.capabilities.systemPromptArg ? systemPromptFor(input.language) : undefined,
             model,
             maxTurns: 1,
         });

package/server/dist/git-guardrails.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitGuardrailError = void 0;
+exports.isForcePush = isForcePush;
+exports.pushesToBranch = pushesToBranch;
+exports.assertGitAllowed = assertGitAllowed;
+/**
+ * Git safety guardrails for the app-owned push/PR path (safe-pr-workflow).
+ *
+ * specrails must NEVER force-push and NEVER push directly to a project's
+ * integration branch — work always lands on a ticket/batch branch and reaches the
+ * integration branch only through a human-merged PR. This is a pure policy check
+ * wired into the sanctioned git/PR path (`pr-publisher`) as defense-in-depth: even
+ * a future bug that constructed a bad push is refused loudly.
+ *
+ * NOTE: this guards the APP's own git invocations. Blocking git issued by the AI
+ * agent *inside* a loop turn (e.g. a rogue `git push --force`) requires a
+ * per-worktree pre-push hook and is a documented follow-up.
+ */
+class GitGuardrailError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitGuardrailError';
+    }
+}
+exports.GitGuardrailError = GitGuardrailError;
+const FORCE_FLAGS = new Set(['--force', '-f', '--force-with-lease']);
+/** True when a `git push` arg list carries a force flag (incl. `--force-with-lease=…`). */
+function isForcePush(args) {
+    return args[0] === 'push' && args.some((a) => FORCE_FLAGS.has(a) || a.startsWith('--force-with-lease='));
+}
+/**
+ * Does a `git push` arg list target the protected branch? Catches
+ *   push <remote> <protected>        (implicit same-name)
+ *   push <remote> HEAD:<protected>   (explicit dst refspec)
+ *   push <remote> <src>:<protected>
+ * We only ever push the ticket/batch branch, so any of these is a bug.
+ */
+function pushesToBranch(args, branch) {
+    if (args[0] !== 'push' || !branch)
+        return false;
+    return args.slice(1).some((a) => {
+        if (a.startsWith('-'))
+            return false; // a flag, not a refspec
+        const dst = a.includes(':') ? a.slice(a.indexOf(':') + 1) : a;
+        return dst === branch || dst === `refs/heads/${branch}`;
+    });
+}
+/**
+ * Throw if a git command violates the guardrails. Only `push` is policed today;
+ * every other command is allowed through unchanged.
+ */
+function assertGitAllowed(cmd, args, opts = {}) {
+    if (cmd !== 'git' || args[0] !== 'push')
+        return;
+    if (isForcePush(args)) {
+        throw new GitGuardrailError('force-push is not allowed on the safe-PR path');
+    }
+    if (opts.protectedBranch && pushesToBranch(args, opts.protectedBranch)) {
+        throw new GitGuardrailError(`direct push to the integration branch "${opts.protectedBranch}" is not allowed`);
+    }
+}

package/server/dist/index.js

@@ -26,6 +26,7 @@ const mobile_1 = require("./mobile");
 const mcp_1 = require("./mcp");
 const agent_chat_manager_1 = require("./agent-chat-manager");
 const agent_chat_router_1 = require("./agent-chat-router");
+const agent_chat_registry_1 = require("./agent-chat-registry");
 const browser_playwright_1 = require("./browser-playwright");
 const telemetry_receiver_1 = require("./telemetry-receiver");
 const telemetry_compactor_1 = require("./telemetry-compactor");
@@ -542,6 +543,10 @@ function applyPtyWsRateLimiting(ws) {
     // ─── App-global agent chat (drives the app via its own MCP) ────────────────
     const agentChatManager = new agent_chat_manager_1.AgentChatManager(broadcast, registry.desktopDb, port);
     _agentChatManager = agentChatManager;
+    // Publish the instance to the process-wide registry so the rails layer can
+    // post PR-decision cards (safe-pr-review-flow). Left null when agent chat is
+    // disabled — the rails callers are null-safe and simply skip the card.
+    (0, agent_chat_registry_1.setAgentChatManager)((0, agent_chat_router_1.isAgentChatEnabled)() ? agentChatManager : null);
     app.use('/api/agent', (0, agent_chat_router_1.createAgentChatRouter)({ manager: agentChatManager, desktopDb: registry.desktopDb }));
     // App-level routes. CRITICAL mount order: the desktop router is mounted at
     // '/api' BEFORE the project router below so its exact routes (e.g.