specrails-desktop 2.64.2 → 2.65.0

package/server/dist/project-registry.js

@@ -15,6 +15,10 @@ const db_1 = require("./db");
 const project_repositories_1 = require("./project-repositories");
 const multi_repo_execution_store_1 = require("./modules/delivery/runtime/multi-repo-execution-store");
 const queue_manager_1 = require("./modules/execution/runtime/queue-manager");
+const daily_budget_gate_1 = require("./modules/execution/runtime/daily-budget-gate");
+const budget_storage_1 = require("./modules/execution/adapters/budget-storage");
+const execution_1 = require("./modules/execution");
+const review_wip_gate_1 = require("./modules/delivery/runtime/review-wip-gate");
 const agent_defaults_1 = require("./modules/agents/runtime/agent-defaults");
 const chat_manager_1 = require("./modules/conversations/runtime/chat-manager");
 const setup_manager_1 = require("./setup-manager");
@@ -30,7 +34,6 @@ const ticket_watcher_1 = require("./modules/specs/runtime/ticket-watcher");
 const terminal_manager_1 = require("./modules/terminals/runtime/terminal-manager");
 const browser_capture_manager_1 = require("./modules/browser/runtime/browser-capture-manager");
 const browser_context_pool_1 = require("./modules/browser/runtime/browser-context-pool");
-const preview_targets_1 = require("./modules/browser/runtime/preview-targets");
 const explore_cwd_manager_1 = require("./modules/conversations/runtime/explore-cwd-manager");
 const hooks_1 = require("./hooks");
 const transient_children_1 = require("./transient-children");
@@ -40,6 +43,8 @@ const workspace_resolution_1 = require("./workspace-resolution");
 const project_env_1 = require("./project-env");
 const workspace_manager_1 = require("./workspace-manager");
 const ticket_store_1 = require("./modules/specs/runtime/ticket-store");
+const non_goals_1 = require("./modules/specs/domain/non-goals");
+const run_records_1 = require("./modules/delivery/runtime/run-records");
 const spec_addenda_1 = require("./modules/specs/runtime/spec-addenda");
 const jira_sync_manager_1 = require("./jira/jira-sync-manager");
 const stuck_run_detector_1 = require("./modules/execution/runtime/stuck-run-detector");
@@ -50,18 +55,31 @@ const blueprint_render_1 = require("./modules/builder/runtime/blueprint-render")
 const worktree_manager_1 = require("./worktree-manager");
 const integration_branch_1 = require("./integration-branch");
 const db_2 = require("./db");
+const runtime_1 = require("./modules/audit/adapters/runtime");
 const loop_run_manager_1 = require("./modules/loops/runtime/loop-run-manager");
 const loop_executors_1 = require("./modules/loops/runtime/loop-executors");
+const flow_review_legacy_1 = require("./modules/delivery/runtime/flow-review-legacy");
 const loop_definition_recovery_1 = require("./modules/loops/runtime/loop-definition-recovery");
 const rail_isolated_launch_1 = require("./modules/delivery/runtime/rail-isolated-launch");
 const rail_isolation_1 = require("./modules/delivery/runtime/rail-isolation");
 const rail_pr_store_1 = require("./modules/delivery/runtime/rail-pr-store");
 const agent_chat_registry_1 = require("./modules/missions/runtime/agent-chat-registry");
 const rail_pr_ticket_effects_1 = require("./modules/delivery/runtime/rail-pr-ticket-effects");
+const rail_pr_decision_1 = require("./modules/delivery/runtime/rail-pr-decision");
+const pr_publisher_1 = require("./modules/delivery/runtime/pr-publisher");
 const loop_runs_store_1 = require("./modules/loops/runtime/loop-runs-store");
 const rails_store_1 = require("./modules/delivery/runtime/rails-store");
 const desktop_db_1 = require("./desktop-db");
 const config_1 = require("./config");
+const flow_1 = require("./modules/flow");
+const sqlite_1 = require("./modules/flow/adapters/sqlite");
+const bindings_1 = require("./modules/flow/adapters/bindings");
+const triage_1 = require("./modules/specs/runtime/triage");
+const ticket_trash_service_1 = require("./modules/specs/runtime/ticket-trash-service");
+const attachment_manager_1 = require("./attachment-manager");
+const rules_inventory_runs_1 = require("./modules/project-rules/runtime/rules-inventory-runs");
+const core_capabilities_1 = require("./modules/agent-runtime/runtime/core-capabilities");
+const core_sessions_availability_1 = require("./modules/agent-sessions/runtime/core-sessions-availability");
 const process_admission_1 = require("./process-admission");
 // ─── Types ────────────────────────────────────────────────────────────────────
 /** The two live queue states are the only non-terminal members of JobStatus.
@@ -120,9 +138,6 @@ class ProjectRegistry {
     // Chromium profile under ~/.specrails/browser-profile, so cookies/logins are
     // shared across every project. Launched lazily, disposed once at shutdown().
     _browserContextPool;
-    // Companion app preview: URLs announced by running mission processes,
-    // derived on demand from their logs (shared by every project's browser).
-    _previewTargets = (0, preview_targets_1.createPreviewTargetSource)();
     constructor(broadcast, desktopDbPath, desktopPort) {
         this._broadcast = broadcast;
         this._desktopDb = (0, desktop_db_1.initDesktopDb)(desktopDbPath ?? (0, desktop_db_1.getDesktopDbPath)());
@@ -132,9 +147,6 @@ class ProjectRegistry {
         this._failedProjects = new Map();
         this._browserContextPool = new browser_context_pool_1.SharedBrowserContextPool();
     }
-    get previewTargets() {
-        return this._previewTargets;
-    }
     get desktopDb() {
         return this._desktopDb;
     }
@@ -277,6 +289,7 @@ class ProjectRegistry {
     }
     removeProject(id) {
         this._clearLoadRetry(id);
+        rules_inventory_runs_1.rulesInventoryRuns.forget(id);
         // Resolve the repo path BEFORE the DB row is deleted below so we can drop the
         // shared artifact-registry entry. Prefer the live context, fall back to the
         // desktop DB row (project may be registered-but-not-loaded, e.g. M9 failure).
@@ -368,6 +381,10 @@ class ProjectRegistry {
                 ctx.milestoneProgress?.dispose();
             }
             catch { /* ignore */ }
+            try {
+                ctx.flowSettlement?.stop();
+            }
+            catch { /* ignore */ }
             // Kill any terminal sessions belonging to this project
             try {
                 (0, terminal_manager_1.getTerminalManager)().killAllForProject(id);
@@ -382,6 +399,14 @@ class ProjectRegistry {
                 ctx.fileSummaryManager.dispose();
             }
             catch { /* ignore */ }
+            try {
+                ctx.specTriage?.dispose();
+            }
+            catch { /* ignore */ }
+            try {
+                ctx.trashPurge?.stop();
+            }
+            catch { /* ignore */ }
             // Drop the app-managed Explore Spec cwd (CLAUDE.md + symlink to project)
             try {
                 (0, explore_cwd_manager_1.removeExploreCwd)(ctx.project.slug);
@@ -402,6 +427,11 @@ class ProjectRegistry {
                 (0, project_env_1.stopProjectEnvWarmup)(ctx.db);
             }
             catch { /* ignore */ }
+            // Flush pending audit rows and stop retention BEFORE the connection closes.
+            try {
+                ctx.agentAudit?.dispose();
+            }
+            catch { /* ignore */ }
             // Close the DB connection BEFORE removing the project's data dir below.
             try {
                 ctx.db.close();
@@ -645,16 +675,32 @@ class ProjectRegistry {
                 ctx.milestoneProgress?.dispose();
             }
             catch { /* ignore */ }
+            try {
+                ctx.flowSettlement?.stop();
+            }
+            catch { /* ignore */ }
             // Release chokidar watchers + abort in-flight generations so a restart
             // does not leak handles/children — mirror removeProject()'s per-project teardown.
             try {
                 ctx.fileSummaryManager.dispose();
             }
             catch { /* ignore */ }
+            try {
+                ctx.specTriage?.dispose();
+            }
+            catch { /* ignore */ }
+            try {
+                ctx.trashPurge?.stop();
+            }
+            catch { /* ignore */ }
             try {
                 (0, project_env_1.stopProjectEnvWarmup)(ctx.db);
             }
             catch { /* ignore */ }
+            try {
+                ctx.agentAudit?.dispose();
+            }
+            catch { /* ignore */ }
             ctx.ticketWatcher.close().catch(() => { });
         }
         // Close the shared browser context once, after every per-project manager has
@@ -695,6 +741,8 @@ class ProjectRegistry {
         // once the rail maps exist; null until then (startup messages are few).
         let milestoneProgress = null;
         let milestoneChains = null;
+        let flowService = null;
+        let specTriage = null;
         const boundBroadcast = (msg) => {
             const enriched = { ...msg, projectId: project.id };
             this._broadcast(enriched);
@@ -702,6 +750,14 @@ class ProjectRegistry {
             // emit its own `milestone.chain_changed`; the progress tap then coalesces.
             milestoneChains?.observe(msg);
             milestoneProgress?.observe(msg);
+            // Spec triage: a created/edited spec schedules a debounced triage scan.
+            specTriage?.observe(msg);
+            // Flow settlement: a Flow delivery that reached review settles its Flow.
+            if (msg.type === 'rail.pr_state' && flowService) {
+                const deliveryId = msg.prDeliveryId;
+                if (typeof deliveryId === 'string')
+                    void flowService.observeDelivery(deliveryId).catch((err) => console.error('[flow] delivery settlement failed:', err));
+            }
             if (msg.type === 'queue') {
                 for (const job of msg.jobs) {
                     if (isTerminalJobStatus(job.status)) {
@@ -735,8 +791,15 @@ class ProjectRegistry {
             projectPath: project.path,
             broadcast: boundBroadcast,
         });
+        // Agent actions audit (one batched writer per project connection). Retention
+        // runs shortly after startup and daily, reading the project setting each time.
+        const agentAudit = (0, runtime_1.createProjectAgentAudit)(db, {
+            label: project.slug,
+            retentionDays: () => (0, db_2.getProjectSettings)(db).agentAuditRetentionDays,
+        });
         const queueManager = new queue_manager_1.QueueManager(boundBroadcast, db, undefined, project.path, {
             zombieTimeoutMs: projectZombieTimeout,
+            agentAudit: agentAudit.recorder,
             provider: project.provider ?? 'claude',
             projectId: project.id,
             projectSlug: project.slug,
@@ -769,16 +832,8 @@ class ProjectRegistry {
                 const val = (0, desktop_db_1.getDesktopSetting)(this._desktopDb, 'cost_alert_threshold_usd');
                 return val != null ? parseFloat(val) : null;
             },
-            getDesktopDailyBudget: () => {
-                const val = (0, desktop_db_1.getDesktopSetting)(this._desktopDb, 'desktop_daily_budget_usd');
-                const budget = val != null ? parseFloat(val) : null;
-                let totalSpend = 0;
-                for (const c of this.listContexts()) {
-                    const row = c.db.prepare(`SELECT COALESCE(SUM(total_cost_usd), 0) as total FROM jobs WHERE status = 'completed' AND total_cost_usd IS NOT NULL AND started_at >= date('now')`).get();
-                    totalSpend += row.total;
-                }
-                return { budget, totalSpend };
-            },
+            getDesktopDailyBudget: () => this._desktopDailyBudgetSnapshot(),
+            getPeriodCapBreaches: () => this._capStatuses(db, project.id).filter((cap) => cap.exhausted && cap.period !== 'day'),
             onBudgetExceeded: (event, data) => {
                 if (event === 'desktop_daily_budget_exceeded') {
                     this._pauseAllQueuesForDesktopBudget();
@@ -1009,7 +1064,9 @@ class ProjectRegistry {
                             // On a replay after the ticket mutation committed but a later rail
                             // mutation failed, changedTicketIds is empty. Derive the intended
                             // review set from the converged store so Jira still receives it.
-                            const reviewIds = effectTicketIds.filter((tid) => outcomeStore?.tickets[String(tid)]?.status === 'on_review');
+                            // A Flow spec reaches Jira only through its Flow settlement
+                            // (create, then the review transition), never from here.
+                            const reviewIds = effectTicketIds.filter((tid) => outcomeStore?.tickets[String(tid)]?.status === 'on_review' && !(0, ticket_store_1.isFlowHeldTicket)(outcomeStore?.tickets[String(tid)]));
                             jiraSyncManager.onRailReview(reviewIds, jobId);
                         }
                         else {
@@ -1067,7 +1124,16 @@ class ProjectRegistry {
         // LOW-2: resolve the per-project DB so phase-4 setup-chat AI turns record
         // an `ai_invocations` row (surface='setup'). Returns null until the project
         // context exists, in which case nothing is recorded (best-effort).
-        (pid) => this._contexts.get(pid)?.db ?? null);
+        (pid) => this._contexts.get(pid)?.db ?? null, 
+        // After a setup succeeded, run Core's rules inventory once in the
+        // background (gated on Core `rulesInventory`; idempotent; a failure is
+        // logged and shown in the project's rules panel). Never blocks setup.
+        (pid) => {
+            const target = this._contexts.get(pid)?.project;
+            if (!target)
+                return;
+            void rules_inventory_runs_1.rulesInventoryRuns.runAfterSetup({ id: target.id, slug: target.slug, path: target.path }, async () => (await (0, core_capabilities_1.corePhase3Capabilities)()).rulesInventory);
+        });
         const proposalManager = new proposal_manager_1.ProposalManager(boundBroadcast, db, project.path, project.id, project.provider ?? 'claude', project.slug);
         const agentRefineManager = new agent_refine_manager_1.AgentRefineManager(boundBroadcast, db, project.path, project.id, project.provider ?? 'claude');
         // Retention prune: drop stale/abandoned refine sessions on project load.
@@ -1143,9 +1209,6 @@ class ProjectRegistry {
             // Share ONE persistent Chromium profile (global cookies/logins) across all
             // projects instead of a per-project profile.
             contextPool: this._browserContextPool,
-            // Only device-owned (Companion preview) sessions may load these loopback
-            // origins; Desktop sessions keep the regular SSRF guard.
-            previewOrigins: () => this._previewTargets.announcedOrigins(project.id),
         });
         // ── Loops engine (the Loops feature) ──────────────────────────────────────
         const railLoopRuns = new Map();
@@ -1165,14 +1228,45 @@ class ProjectRegistry {
         // per-run (the worktree for isolated runs). Legacy projects keep process.env
         // byte-identical except for the explicit per-project passthrough overlay.
         // See resolveLoopBaseEnv.
+        // Same budget state the queue auto-pause enforces; bound to THIS project's
+        // connection (project budget) plus the app-wide snapshot.
+        const capOptions = { db, projectId: project.id, desktop: () => this._desktopDailyBudgetSnapshot(), desktopPeriod: (period, at) => this._desktopPeriodSnapshot(period, at) };
+        const dailyBudgetRejection = (0, daily_budget_gate_1.createDailyBudgetGate)(capOptions);
+        const dailyBudgetHeadroom = (0, daily_budget_gate_1.createDailyBudgetHeadroom)(capOptions);
+        // Every configured cap with its spend (Budget panel, inbox, mid-run pause).
+        const budgetCaps = (at = new Date()) => (0, daily_budget_gate_1.readCapStatuses)(capOptions, at);
+        // The per-run soft cap that applies to a new run: the tighter of the
+        // project's and the app-wide default (null = none).
+        const runCapDefault = () => (0, execution_1.effectiveRunCap)((0, budget_storage_1.readProjectCaps)(db).run, this._desktopCapConfig().run);
+        const reviewWipGate = (0, review_wip_gate_1.createReviewWipGate)({ db, readLimit: () => (0, db_2.getProjectSettings)(db).reviewWipLimit });
+        // Architect clarifications (feedback-2026-10 task 3.2): after a Core
+        // invocation pauses or ends, post the run's clarifications record to the
+        // linked Jira issues when the project opted in. Core writes no record
+        // without `architectClarifications: 1`, so older Cores never post.
+        const publishRunClarifications = (runId, ticketIds) => {
+            if (ticketIds.length === 0 || !(0, db_2.getProjectSettings)(db).jiraPostClarifications || !jiraSyncManager.isActive())
+                return;
+            try {
+                const runtimeDir = path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(project).specrailsDir, 'pipeline', runId);
+                const record = (0, run_records_1.readClarifications)(runtimeDir, run_records_1.nodeRunRecordFs);
+                if (record)
+                    jiraSyncManager.onRunClarifications(runId, ticketIds, record);
+            }
+            catch (err) {
+                console.error(`[jira-sync] clarifications for ${runId} failed:`, err);
+            }
+        };
         const loopRunManager = new loop_run_manager_1.LoopRunManager(db, boundBroadcast, (0, loop_executors_1.createLoopExecutors)({
             pluginScope: () => ({ stateRoot: (0, workspace_resolution_1.resolveProjectExecution)(project).cwd, legacyProviderId: project.provider }),
             // A project registered as a package of a larger checkout scopes Core to that package in isolated worktrees.
             sourcePath: () => (0, project_repositories_1.resolveProjectRepository)(project).path,
             workspacePaths: () => { const primary = (0, project_repositories_1.resolveProjectRepository)(project); return primary.workspacePaths ?? (primary.workspacePath ? [primary.workspacePath] : undefined); },
-            env: () => (0, workspace_resolution_1.resolveLoopBaseEnv)({ slug: project.slug, path: project.path }, undefined, (0, project_env_1.applyWorktreeEnvPassthrough)(db, process.env)),
+            // `minimal` agent environment: the step's provider names ride along.
+            env: (providerAllowlist) => (0, workspace_resolution_1.resolveLoopBaseEnv)({ slug: project.slug, path: project.path }, undefined, (0, project_env_1.resolveProjectAgentEnv)(db, { providerAllowlist })),
             // One value-free run-log line when configured names are unresolved.
             environmentNotice: () => (0, project_env_1.worktreeEnvPassthroughWarning)(db, (0, project_env_1.applyWorktreeEnvPassthrough)(db, process.env)),
+            // Phase-3 project switches Core reads from its config (capability-gated in the bridge).
+            projectRuntime: () => ({ baselineOnTouch: (0, db_2.getProjectSettings)(db).baselineOnTouch }),
             // Named rail profiles and global per-agent defaults ride the same
             // SPECRAILS_PROFILE_PATH snapshot in both AI transports. An explicit null
             // rail selection opts out; omitted selections keep Core's default rules.
@@ -1181,7 +1275,7 @@ class ProjectRegistry {
                 profileRoot: () => (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path }).cwd,
                 supportsProfiles: project_profile_support_1.projectSupportsProfiles,
             }),
-        }));
+        }), undefined, { dailyBudget: dailyBudgetRejection, runCapDefault, agentAudit: agentAudit.recorder, onDefinitionInvocationEnd: (runId, ticketIds) => publishRunClarifications(runId, ticketIds) });
         const getTicketSpec = (ticketId) => {
             try {
                 const exec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path });
@@ -1193,7 +1287,8 @@ class ProjectRegistry {
                 return {
                     id: t.id,
                     title: t.title,
-                    description: t.description,
+                    // Non-goals (3.2) ride in the description every loop prompt sees.
+                    description: (0, non_goals_1.descriptionWithNonGoals)(t.description, t.nonGoals),
                     status: t.status,
                     priority: t.priority,
                     labels: t.labels,
@@ -1264,6 +1359,8 @@ class ProjectRegistry {
                 }
             }
             const ticketIds = payload?.ticketIds ?? meta?.ticketIds ?? [];
+            // Idempotent per record: a pause already posted is not posted again.
+            publishRunClarifications(runId, ticketIds);
             const railIndex = payload?.railIndex ?? meta?.railIndex ?? null;
             const effectiveOutcome = payload?.outcome ?? outcome;
             const status = effectiveOutcome === 'success' ? 'completed'
@@ -1325,7 +1422,10 @@ class ProjectRegistry {
                     if (store && effectTicketIds.length > 0) {
                         try {
                             if (status === 'completed' && completedStatus === 'on_review') {
-                                const reviewIds = effectTicketIds.filter((ticketId) => store?.tickets[String(ticketId)]?.status === 'on_review');
+                                // Flow specs: the Flow settlement creates the Jira issue first and
+                                // then transitions it; an early review here would be a no-op at
+                                // best and a double transition at worst.
+                                const reviewIds = effectTicketIds.filter((ticketId) => store?.tickets[String(ticketId)]?.status === 'on_review' && !(0, ticket_store_1.isFlowHeldTicket)(store?.tickets[String(ticketId)]));
                                 jiraSyncManager.onRailReview(reviewIds, runId);
                             }
                             else {
@@ -1350,6 +1450,15 @@ class ProjectRegistry {
                 });
                 const delivered = deliver();
                 railLoopRuns.delete(runId);
+                // Flow hand-off without a PR delivery row: the completed run settles the
+                // Flow (with a delivery row, the `rail.pr_state` observer does).
+                if (status === 'completed' && flowService) {
+                    for (const ticketId of ticketIds) {
+                        const flowId = delivered.store?.tickets[String(ticketId)]?.metadata?.flow?.flowId;
+                        if (flowId)
+                            void flowService.onRailRunCompleted({ flowId, runId }).catch((err) => console.error('[flow] run settlement failed:', err));
+                    }
+                }
                 // Milestone chain fallback hook: records the engine outcome (names the
                 // pause reason) and settles delivery-less chunks. Isolated chunks
                 // advance from the later `rail.pr_state` settle instead.
@@ -1504,8 +1613,51 @@ class ProjectRegistry {
             persistDone: (milestoneId) => (0, milestone_progress_1.markMilestoneDone)(blueprintWorkspace(), milestoneId) !== null,
             broadcast: boundBroadcast,
         });
-        const ctx = { project, db, queueManager, chatManager, setupManager, proposalManager, agentRefineManager, fileSummaryManager, specLauncherManager, ticketWatcher, browserCaptureManager, jiraSyncManager, stuckRunDetector, broadcast: boundBroadcast, railJobs, loopRunManager, railLoopRuns, onLoopRunFinished, getTicketSpec, desktopDb: this._desktopDb, milestoneProgress };
+        const ctx = { project, db, queueManager, chatManager, setupManager, proposalManager, agentRefineManager, fileSummaryManager, specLauncherManager, ticketWatcher, browserCaptureManager, jiraSyncManager, stuckRunDetector, broadcast: boundBroadcast, railJobs, loopRunManager, railLoopRuns, onLoopRunFinished, getTicketSpec, desktopDb: this._desktopDb, milestoneProgress, dailyBudgetRejection, dailyBudgetHeadroom, budgetCaps, runCapDefault, reviewWipGate, agentAudit };
         ctx.milestoneChains = milestoneChains;
+        // Spec triage (launch-triage): cheap per-spec loop recommendation. Seeded
+        // now so the existing backlog is only triaged on edit or on demand.
+        specTriage = new triage_1.SpecTriageService({
+            project, db, ticketsPath: ticketStorePath, broadcast: boundBroadcast,
+            notifyDesktopWrite: (revision) => ticketWatcher.notifyDesktopWrite(revision),
+        });
+        specTriage.start();
+        ctx.specTriage = specTriage;
+        // Recently deleted specs: purge past the 30-day window at startup and on a timer.
+        ctx.trashPurge = (0, ticket_trash_service_1.startProjectTrashPurge)({
+            ticketStorePath,
+            db,
+            deleteAttachments: (ticketKey) => attachment_manager_1.attachmentManager.deleteAll(project.slug, ticketKey),
+            forgetExploreConversation: (conversationId) => {
+                chatManager?.forgetSpecDraft(conversationId);
+                chatManager?.forgetExploreLifecycle(conversationId);
+            },
+        });
+        // Flow mode: use cases bound to THIS project's connection; the mission host
+        // is app-global and late-bound (agent chat starts after the registry).
+        const flowRepository = (0, sqlite_1.createSqliteFlowRepository)(db);
+        const flowPorts = (0, bindings_1.createFlowPorts)({
+            ctx, repository: flowRepository, effects: (0, sqlite_1.createSqliteFlowEffectsStore)(db), internalApi, availability: () => (0, core_sessions_availability_1.flowAvailability)(),
+            agentHost: () => (0, agent_chat_registry_1.getAgentChatManager)(),
+            // Dev servers the Flow agent started in the worktree stop with the Flow.
+            processes: {
+                async stop({ flowId }) {
+                    const { unresolved } = await (0, transient_children_1.stopBackgroundProcessesForFlow)(flowId, project.id);
+                    if (unresolved.length)
+                        console.warn(`[flow] ${unresolved.length} background process(es) of Flow ${flowId} did not confirm exit`);
+                },
+            },
+        });
+        ctx.flow = (0, flow_1.createFlowService)(flowPorts);
+        flowService = ctx.flow;
+        ctx.flowHandOff = (0, bindings_1.createFlowHandOffAuthority)(flowRepository, bindings_1.systemClock, (session) => flowPorts.notifier.changed(session), 
+        // Flow -> Spec: the bounded conversation summary Core's derive-change reads.
+        (session) => (0, bindings_1.flowConversationSummary)(this._desktopDb, {
+            conversationId: session.conversationId,
+            idea: session.ticketId !== null ? getTicketSpec(session.ticketId)?.description ?? null : null,
+            from: session.createdAt,
+            to: null,
+        }));
         this._contexts.set(project.id, ctx);
         // Warm the project's login-shell env cache off the event loop so the first
         // rail/loop spawn reads recovered credentials instead of a cold 1.5 s probe.
@@ -1529,6 +1681,20 @@ class ProjectRegistry {
                     .then(async (n) => {
                     if (n > 0)
                         console.log(`[loops] reconciled ${n} orphan worktree(s) for ${project.slug}`);
+                    // Flow sessions never survive a restart; unfinished sagas complete
+                    // or compensate before admission opens (never throws).
+                    if (this._contexts.get(project.id) === ctx && ctx.flow) {
+                        const flows = await ctx.flow.reconcile();
+                        if (flows.length > 0)
+                            console.log(`[flow] reconciled ${flows.length} Flow session(s) for ${project.slug}`);
+                        // Settlement effects survive restarts: deliveries that reached
+                        // review while the app was down settle now; pending effects resume.
+                        const settled = await ctx.flow.replaySettlement();
+                        if (settled > 0)
+                            console.log(`[flow] resumed settlement of ${settled} Flow(s) for ${project.slug}`);
+                        if (this._contexts.get(project.id) === ctx && !ctx.flowSettlement)
+                            ctx.flowSettlement = (0, bindings_1.startFlowSettlementScheduler)(ctx.flow);
+                    }
                     if (this._contexts.get(project.id) === ctx) {
                         const effectDeps = {
                             db,
@@ -1552,8 +1718,30 @@ class ProjectRegistry {
                         });
                         if (!ticketEffects.settled || this._contexts.get(project.id) !== ctx)
                             return;
+                        // "Integrate locally" saved the person's uncommitted work as a
+                        // stash and the app stopped before restoring it: re-apply now,
+                        // before admission opens (never throws; conflicts keep the stash).
+                        const restoredLocalChanges = await (0, rail_pr_decision_1.recoverLocalStashes)({ ...effectDeps, git: worktree_manager_1.defaultGitRunner, exec: pr_publisher_1.defaultExec });
+                        for (const deliveryId of restoredLocalChanges)
+                            emitRecoveredPrDelivery(ctx, deliveryId);
+                        if (this._contexts.get(project.id) !== ctx)
+                            return;
                         reprojectActivePrDeliveries(ctx);
                         (0, process_admission_1.openProjectProcessAdmission)(project.id);
+                        // Flow -> Spec deliveries settled as a generic failure before the
+                        // review outcome existed: persist the reclassification once (the
+                        // retained ledger is read-only here) and refresh their cards.
+                        void (0, flow_review_legacy_1.healLegacyFlowReviews)({
+                            db,
+                            pipelineDir: path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)({ slug: project.slug, path: project.path }).specrailsDir, 'pipeline'),
+                            probe: (runIds) => (0, loop_definition_recovery_1.probeDefinitionRuns)({ db, cwd: project.path, env: process.env }, runIds, true),
+                            isDefinitionRun: (runId) => (0, loop_runs_store_1.getLoopRun)(db, runId)?.engine_version === 2,
+                        }).then((ids) => {
+                            if (this._contexts.get(project.id) !== ctx)
+                                return;
+                            for (const deliveryId of ids)
+                                emitRecoveredPrDelivery(ctx, deliveryId);
+                        });
                     }
                 })
                     .catch((err) => {
@@ -1637,6 +1825,55 @@ class ProjectRegistry {
             return false;
         }
     }
+    /** App-wide daily budget state. The queue auto-pause and the rail/loop
+     *  admission gate read this same snapshot, so both doors agree. */
+    _desktopDailyBudgetSnapshot() {
+        const val = (0, desktop_db_1.getDesktopSetting)(this._desktopDb, 'desktop_daily_budget_usd');
+        const budget = val != null ? parseFloat(val) : null;
+        let totalSpend = 0;
+        for (const c of this.listContexts()) {
+            const row = c.db.prepare(`SELECT COALESCE(SUM(total_cost_usd), 0) as total FROM jobs WHERE status = 'completed' AND total_cost_usd IS NOT NULL AND started_at >= date('now')`).get();
+            totalSpend += row.total;
+        }
+        return { budget, totalSpend };
+    }
+    /** App-wide caps (all projects combined) as configured in desktop settings. */
+    _desktopCapConfig() {
+        return (0, budget_storage_1.readDesktopCaps)((key) => (0, desktop_db_1.getDesktopSetting)(this._desktopDb, key));
+    }
+    /** App-wide weekly/monthly cap with the spend of EVERY project in the local period containing `at`. */
+    _desktopPeriodSnapshot(period, at) {
+        const budget = this._desktopCapConfig()[period];
+        if (budget === null)
+            return { budget: null, totalSpend: 0 };
+        const since = (0, execution_1.periodStartIso)(period, at);
+        let totalSpend = 0;
+        for (const c of this.listContexts()) {
+            try {
+                totalSpend += (0, budget_storage_1.projectSpendSince)(c.db, c.project.id, since);
+            }
+            catch { /* an unreadable project adds nothing (fail-open) */ }
+        }
+        return { budget, totalSpend };
+    }
+    /** The app-wide caps with their spend (all projects combined), for the Budget panel. */
+    desktopCapStatuses(at = new Date()) {
+        const out = [];
+        const day = this._desktopDailyBudgetSnapshot();
+        const push = (period, snapshot, resetsAt) => {
+            if (snapshot.budget == null || !(snapshot.budget > 0))
+                return;
+            out.push({ scope: 'desktop', period, budgetUsd: snapshot.budget, spentUsd: snapshot.totalSpend, exhausted: (0, execution_1.isCapExceeded)(snapshot.budget, snapshot.totalSpend), resetsAt });
+        };
+        push('day', day, (0, execution_1.dailyBudgetResetsAt)('desktop', at));
+        push('week', this._desktopPeriodSnapshot('week', at), (0, execution_1.periodResetsAtIso)('week', at));
+        push('month', this._desktopPeriodSnapshot('month', at), (0, execution_1.periodResetsAtIso)('month', at));
+        return out;
+    }
+    /** Every cap of one project plus the app-wide ones, with spend. */
+    _capStatuses(db, projectId, at = new Date()) {
+        return (0, daily_budget_gate_1.readCapStatuses)({ db, projectId, desktop: () => this._desktopDailyBudgetSnapshot(), desktopPeriod: (period, when) => this._desktopPeriodSnapshot(period, when) }, at);
+    }
     /** Enforce the app-wide budget through every per-project queue authority. */
     _pauseAllQueuesForDesktopBudget() {
         for (const context of this.listContexts()) {

package/server/dist/project-router-background-processes.js

@@ -4,6 +4,19 @@ exports.registerBackgroundProcessRoutes = registerBackgroundProcessRoutes;
 const transient_children_1 = require("./transient-children");
 const project_repositories_1 = require("./project-repositories");
 const background_process_service_1 = require("./modules/terminals/runtime/background-process-service");
+const app_urls_1 = require("./modules/terminals/runtime/app-urls");
+/** The chat's ACTIVE Flow with a worktree (null when none or the lookup fails). */
+function activeFlow(c, chatId) {
+    try {
+        const flow = c.flow?.getByConversation(chatId);
+        if (!flow || flow.state !== 'active' || flow.step !== null || !flow.worktreePath)
+            return null;
+        return { flowId: flow.id, worktreePath: flow.worktreePath, ...(flow.repositoryId ? { repositoryId: flow.repositoryId } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
 function processQuery(req, res) {
     const pid = Number(req.params.pid);
     if (!Number.isSafeInteger(pid) || pid <= 0) {
@@ -27,7 +40,7 @@ function registerBackgroundProcessRoutes({ router, ctx }) {
         const c = ctx(req);
         const chatId = typeof req.query.chatId === 'string' && req.query.chatId.trim() ? req.query.chatId.trim() : undefined;
         res.json({ processes: (0, transient_children_1.listBackgroundProcesses)({ projectId: c.project.id,
-                ...(chatId ? { chatId } : {}), ...(req.query.includeFinished === 'true' ? { includeFinished: true } : {}) }) });
+                ...(chatId ? { chatId } : {}), ...(req.query.includeFinished === 'true' ? { includeFinished: true } : {}) }).map(app_urls_1.withAppUrls) });
     });
     router.get('/:projectId/background-processes/:pid/logs', (req, res) => {
         const c = ctx(req);
@@ -45,7 +58,7 @@ function registerBackgroundProcessRoutes({ router, ctx }) {
             res.status(404).json({ error: 'background process logs not found for project/chat or execution has expired' });
             return;
         }
-        res.json(logs);
+        res.json({ ...logs, process: (0, app_urls_1.withAppUrls)(logs.process) });
     });
     router.post('/:projectId/background-processes', (req, res) => {
         const { command, cwd, chatId, repositoryId, confirmed, allowWhileBusy } = req.body ?? {};
@@ -70,7 +83,18 @@ function registerBackgroundProcessRoutes({ router, ctx }) {
             }
             if (repositoryId !== undefined && (typeof repositoryId !== 'string' || !repositoryId.trim()))
                 throw new project_repositories_1.RepositoryValidationError('repositoryId must be a nonempty string');
-            if ((0, project_repositories_1.getProjectRepositories)(c.project).length > 1 && repositoryId === undefined)
+            const multiRepository = (0, project_repositories_1.getProjectRepositories)(c.project).length > 1;
+            // Inside an ACTIVE Flow of a multi-repository project the repository is
+            // the Flow's own: the process runs in the Flow worktree, tagged with the
+            // Flow so it stops with it (as the in-app agent's background_start does).
+            const flow = multiRepository && repositoryId === undefined ? activeFlow(c, chatId.trim()) : null;
+            if (flow) {
+                const repository = (0, project_repositories_1.resolveProjectRepository)(c.project, flow.repositoryId);
+                const process = (0, transient_children_1.startBackgroundProcess)(command.trim(), (0, background_process_service_1.resolveBackgroundCwd)(flow.worktreePath, cwd, 'the Flow worktree'), chatId.trim(), c.project.id, (0, background_process_service_1.backgroundProcessHooks)(c.broadcast), { repositoryId: repository.id, repositoryName: repository.name, flowId: flow.flowId });
+                res.status(202).json({ ok: true, repositoryId: repository.id, flowId: flow.flowId, process });
+                return;
+            }
+            if (multiRepository && repositoryId === undefined)
                 throw new project_repositories_1.RepositoryValidationError('repositoryId is required for multi-repository projects', 'repository_required');
             const repository = (0, project_repositories_1.resolveProjectRepository)(c.project, repositoryId);
             const process = (0, transient_children_1.startBackgroundProcess)(command.trim(), (0, background_process_service_1.resolveBackgroundCwd)(repository.path, cwd), chatId.trim(), c.project.id, (0, background_process_service_1.backgroundProcessHooks)(c.broadcast), { repositoryId: repository.id, repositoryName: repository.name });

package/server/dist/project-router-git.js

@@ -155,4 +155,34 @@ function registerGitRoutes(deps) {
             res.status(500).json({ error: 'Checkout failed' });
         }
     });
+    // "Create initial commit" for a repository with an unborn HEAD (shown next to
+    // `repository_has_no_commits`). Primary repository only; an empty commit with
+    // zero files, under the repository lock. 409 when it already has commits or
+    // Git has no author identity.
+    router.post('/:projectId/git/initial-commit', async (req, res) => {
+        const repository = requireGit(req, res, undefined);
+        if (!repository)
+            return;
+        const project = ctx(req).project;
+        try {
+            const admission = (0, process_admission_1.captureProcessAdmission)(project.id);
+            const result = await (0, repo_lock_1.withRepoLock)(repository.path, async () => {
+                admission.assertCurrent();
+                return (0, project_git_1.createInitialCommit)(repository.path);
+            });
+            if (!result.ok) {
+                res.status(result.code === 'initial_commit_failed' ? 500 : 409).json({ error: result.code, detail: result.detail, repositoryId: repository.id });
+                return;
+            }
+            res.status(201).json({ sha: result.sha, repositoryId: repository.id });
+        }
+        catch (err) {
+            if (err instanceof process_admission_1.ProcessAdmissionClosedError) {
+                res.status(409).json({ error: 'project_recovery_in_progress' });
+                return;
+            }
+            console.error('[project-git] initial commit failed:', err);
+            res.status(500).json({ error: 'initial_commit_failed', detail: err instanceof Error ? err.message : String(err) });
+        }
+    });
 }