specrails-desktop 2.64.2 → 2.65.1

package/server/dist/modules/flow/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transition = exports.resolveFlowRepository = exports.placeholderTitle = exports.isTerminalFlow = exports.isOpenFlow = exports.nextFlowCoreSessionId = exports.flowCoreSessionId = exports.summarizeSettlement = exports.nextDueEffect = exports.flowJiraCreateKey = exports.flowEffectKey = exports.extractFlowDecisions = exports.buildSpecRewriteText = exports.firstErrorLine = exports.buildReturnBriefing = exports.buildFlowSummary = exports.OPEN_FLOW_STATES = exports.FLOW_SUMMARY_LIMIT_BYTES = exports.FLOW_SPEC_LOOP_ID = exports.FLOW_SETTLEMENT_ORDER = exports.FlowValidationError = exports.FlowUnavailableError = exports.FlowTransitionError = exports.FlowNotFoundError = exports.FlowLaunchRejectedError = exports.FlowConflictError = exports.createFlowService = void 0;
+// Public application API of the Flow module. Adapters (SQLite, HTTP, port
+// bindings) are wired only at composition roots through their subpaths.
+var application_1 = require("./application");
+Object.defineProperty(exports, "createFlowService", { enumerable: true, get: function () { return application_1.createFlowService; } });
+var domain_1 = require("./domain");
+Object.defineProperty(exports, "FlowConflictError", { enumerable: true, get: function () { return domain_1.FlowConflictError; } });
+Object.defineProperty(exports, "FlowLaunchRejectedError", { enumerable: true, get: function () { return domain_1.FlowLaunchRejectedError; } });
+Object.defineProperty(exports, "FlowNotFoundError", { enumerable: true, get: function () { return domain_1.FlowNotFoundError; } });
+Object.defineProperty(exports, "FlowTransitionError", { enumerable: true, get: function () { return domain_1.FlowTransitionError; } });
+Object.defineProperty(exports, "FlowUnavailableError", { enumerable: true, get: function () { return domain_1.FlowUnavailableError; } });
+Object.defineProperty(exports, "FlowValidationError", { enumerable: true, get: function () { return domain_1.FlowValidationError; } });
+Object.defineProperty(exports, "FLOW_SETTLEMENT_ORDER", { enumerable: true, get: function () { return domain_1.FLOW_SETTLEMENT_ORDER; } });
+Object.defineProperty(exports, "FLOW_SPEC_LOOP_ID", { enumerable: true, get: function () { return domain_1.FLOW_SPEC_LOOP_ID; } });
+Object.defineProperty(exports, "FLOW_SUMMARY_LIMIT_BYTES", { enumerable: true, get: function () { return domain_1.FLOW_SUMMARY_LIMIT_BYTES; } });
+Object.defineProperty(exports, "OPEN_FLOW_STATES", { enumerable: true, get: function () { return domain_1.OPEN_FLOW_STATES; } });
+Object.defineProperty(exports, "buildFlowSummary", { enumerable: true, get: function () { return domain_1.buildFlowSummary; } });
+Object.defineProperty(exports, "buildReturnBriefing", { enumerable: true, get: function () { return domain_1.buildReturnBriefing; } });
+Object.defineProperty(exports, "firstErrorLine", { enumerable: true, get: function () { return domain_1.firstErrorLine; } });
+Object.defineProperty(exports, "buildSpecRewriteText", { enumerable: true, get: function () { return domain_1.buildSpecRewriteText; } });
+Object.defineProperty(exports, "extractFlowDecisions", { enumerable: true, get: function () { return domain_1.extractFlowDecisions; } });
+Object.defineProperty(exports, "flowEffectKey", { enumerable: true, get: function () { return domain_1.flowEffectKey; } });
+Object.defineProperty(exports, "flowJiraCreateKey", { enumerable: true, get: function () { return domain_1.flowJiraCreateKey; } });
+Object.defineProperty(exports, "nextDueEffect", { enumerable: true, get: function () { return domain_1.nextDueEffect; } });
+Object.defineProperty(exports, "summarizeSettlement", { enumerable: true, get: function () { return domain_1.summarizeSettlement; } });
+Object.defineProperty(exports, "flowCoreSessionId", { enumerable: true, get: function () { return domain_1.flowCoreSessionId; } });
+Object.defineProperty(exports, "nextFlowCoreSessionId", { enumerable: true, get: function () { return domain_1.nextFlowCoreSessionId; } });
+Object.defineProperty(exports, "isOpenFlow", { enumerable: true, get: function () { return domain_1.isOpenFlow; } });
+Object.defineProperty(exports, "isTerminalFlow", { enumerable: true, get: function () { return domain_1.isTerminalFlow; } });
+Object.defineProperty(exports, "placeholderTitle", { enumerable: true, get: function () { return domain_1.placeholderTitle; } });
+Object.defineProperty(exports, "resolveFlowRepository", { enumerable: true, get: function () { return domain_1.resolveFlowRepository; } });
+Object.defineProperty(exports, "transition", { enumerable: true, get: function () { return domain_1.transition; } });

package/server/dist/modules/flow/ports.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/server/dist/modules/inbox/adapters/http.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerInboxRoutes = registerInboxRoutes;
+const application_1 = require("../application");
+const project_source_1 = require("./project-source");
+/**
+ * GET /api/inbox — the "Needs you" read-model across projects. Each registered
+ * project is read through its own context and database; nothing is cached or
+ * shared between projects, and the response is a pure projection.
+ */
+function registerInboxRoutes(router, registry) {
+    router.get('/inbox', (_req, res) => {
+        // An app-wide cap belongs to no project: the first project speaks for it so it appears once.
+        const sources = registry.listContexts().map((ctx, index) => (0, project_source_1.createProjectInboxSource)({
+            project: { id: ctx.project.id, name: ctx.project.name },
+            db: ctx.db,
+            caps: () => (ctx.budgetCaps?.() ?? []).filter((cap) => cap.scope === 'project' || index === 0),
+        }));
+        res.json((0, application_1.collectInbox)(sources));
+    });
+}

package/server/dist/modules/inbox/adapters/project-source.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAILED_RUN_WINDOW_MS = void 0;
+exports.createProjectInboxSource = createProjectInboxSource;
+const jira_db_1 = require("../../../jira/jira-db");
+const rail_pr_store_1 = require("../../delivery/runtime/rail-pr-store");
+const sqlite_1 = require("../../recovery/adapters/sqlite");
+const domain_1 = require("../domain");
+/** Finished runs older than this are history, not something that waits for the person. */
+exports.FAILED_RUN_WINDOW_MS = 3 * 24 * 60 * 60 * 1000;
+const MAX_DEAD_JIRA_OPS = 20;
+function parseJsonArray(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function deliveryTitle(row) {
+    const specs = (0, rail_pr_store_1.readSpecSnapshot)(row.spec_snapshot) ?? [];
+    const first = specs.find((s) => s.title)?.title;
+    if (first)
+        return specs.length > 1 ? `${first} +${specs.length - 1}` : first;
+    return row.loop_name || row.rail_key;
+}
+function ticketLabel(raw) {
+    const ids = parseJsonArray(raw).filter((v) => typeof v === 'number');
+    if (ids.length === 0)
+        return '';
+    return ` · ${ids.slice(0, 3).map((id) => `#${id}`).join(', ')}${ids.length > 3 ? ` +${ids.length - 3}` : ''}`;
+}
+/** Provider limits and environment problems wait for the person; they are not defects of the change. */
+function needsHost(diagnosis) {
+    return diagnosis?.confidence === 'high' && (diagnosis.kind === 'provider_limit' || diagnosis.kind === 'environment');
+}
+function deliveryDiagnosis(handle, row) {
+    const runIds = parseJsonArray(row.run_ids).filter((v) => typeof v === 'string');
+    for (const runId of [...runIds].reverse()) {
+        try {
+            const diagnosis = (0, sqlite_1.readRunDiagnosis)(handle.db, runId);
+            if (diagnosis)
+                return diagnosis;
+        }
+        catch { /* the delivery still shows without a diagnosis */ }
+    }
+    return null;
+}
+/** Deliveries that wait for a decision or ended badly, mirroring the client's `deliveryAttention`. */
+function deliveryItems(handle, rows, nowIso) {
+    const out = [];
+    for (const row of rows) {
+        const decision = row.decision;
+        const changesRequested = decision === 'implementation_failed' && row.status_code === 'review_changes_requested';
+        const waiting = decision === 'on_review' || decision === 'pr_draft' || decision === 'pr_ready' || changesRequested;
+        const failed = !changesRequested && (decision === 'implementation_failed' || decision === 'pr_failed');
+        if (!waiting && !failed)
+            continue;
+        // A failed delivery is explained by its last run's diagnosis.
+        const diagnosis = failed ? deliveryDiagnosis(handle, row) : null;
+        const kind = waiting ? 'review' : needsHost(diagnosis) ? 'blocked' : 'failed';
+        out.push({
+            id: (0, domain_1.inboxItemId)(handle.project.id, kind, row.id),
+            projectId: handle.project.id,
+            projectName: handle.project.name,
+            kind,
+            title: deliveryTitle(row),
+            detail: (0, domain_1.oneLine)(row.status_detail) ?? (failed ? (0, domain_1.oneLine)(diagnosis?.detail) ?? row.status_code : null),
+            diagnosis,
+            at: (0, domain_1.toIso)((waiting ? row.on_review_at : null) ?? row.updated_at, nowIso),
+            version: `${decision}:${row.status_code ?? ''}:${row.pr_state}`,
+            action: 'open-review',
+            subjectId: row.id,
+            conversationId: row.origin_conversation_id,
+            decision,
+            ...(Number.isInteger(row.rail_index) ? { railIndex: row.rail_index } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Runs that stopped on something the person must resolve: paused on a budget or
+ * a human decision, interrupted by a restart, blocked, or ended badly (and not
+ * superseded by a later run of the same loop on the same rail). Runs a
+ * delivery already represents are left to the delivery.
+ */
+function runItems(handle, representedRunIds, nowIso, nowMs) {
+    const since = new Date(nowMs - exports.FAILED_RUN_WINDOW_MS).toISOString();
+    const rows = handle.db.prepare(`
+    SELECT r.id, r.loop_name, r.status, r.final_outcome, r.restart_reason, r.started_at, r.finished_at, r.ticket_ids_json, r.rail_index, r.failure_diagnosis
+    FROM loop_runs r
+    WHERE r.project_id = ?
+      AND NOT EXISTS (SELECT 1 FROM definition_fork_operations f WHERE f.source_run_id = r.id AND f.adopted = 1)
+      AND (
+        (r.status = 'paused' AND COALESCE(r.restart_reason, '') != 'fork')
+        OR (r.status = 'completed' AND r.final_outcome IN ('failed','blocked','stalled') AND r.finished_at >= ?
+            AND NOT EXISTS (
+              SELECT 1 FROM loop_runs n
+              WHERE n.project_id = r.project_id AND n.loop_id = r.loop_id
+                AND COALESCE(n.rail_index, -1) = COALESCE(r.rail_index, -1)
+                AND n.started_at > r.started_at))
+      )
+    ORDER BY r.started_at DESC
+    LIMIT 100
+  `).all(handle.project.id, since);
+    const out = [];
+    for (const run of rows) {
+        if (representedRunIds.has(run.id))
+            continue;
+        const title = `${run.loop_name || 'Run'}${ticketLabel(run.ticket_ids_json)}`;
+        const version = `${run.status}:${run.final_outcome ?? ''}:${run.restart_reason ?? ''}`;
+        const base = {
+            projectId: handle.project.id,
+            projectName: handle.project.name,
+            title,
+            version,
+            subjectId: run.id,
+            conversationId: null,
+            diagnosis: null,
+            ...(typeof run.rail_index === 'number' ? { railIndex: run.rail_index } : {}),
+        };
+        if (run.status === 'paused') {
+            if (run.restart_reason === 'budget_paused') {
+                out.push({ ...base, id: (0, domain_1.inboxItemId)(handle.project.id, 'budget', run.id), kind: 'budget', detail: null, at: (0, domain_1.toIso)(run.started_at, nowIso), action: 'resume-run' });
+            }
+            else if (run.restart_reason === 'restart') {
+                out.push({ ...base, id: (0, domain_1.inboxItemId)(handle.project.id, 'blocked', run.id), kind: 'blocked', detail: 'interrupted', at: (0, domain_1.toIso)(run.started_at, nowIso), action: 'resume-run' });
+            }
+            else {
+                out.push({ ...base, id: (0, domain_1.inboxItemId)(handle.project.id, 'question', run.id), kind: 'question', detail: null, at: (0, domain_1.toIso)(run.started_at, nowIso), action: 'open-run' });
+            }
+            continue;
+        }
+        const diagnosis = (0, sqlite_1.readRunDiagnosis)(handle.db, run.id);
+        const kind = run.final_outcome === 'blocked' || needsHost(diagnosis) ? 'blocked' : 'failed';
+        // The version moves with the cause, so a run re-diagnosed differently comes back.
+        out.push({
+            ...base, id: (0, domain_1.inboxItemId)(handle.project.id, kind, run.id), kind, diagnosis,
+            version: `${version}:${diagnosis?.kind ?? ''}:${diagnosis?.confidence ?? ''}`,
+            detail: (0, domain_1.oneLine)(diagnosis?.detail) ?? run.final_outcome, at: (0, domain_1.toIso)(run.finished_at, nowIso), action: 'open-run',
+        });
+    }
+    return out;
+}
+function jiraItems(handle, nowIso) {
+    return (0, jira_db_1.listOutbox)(handle.db, { state: 'dead', limit: MAX_DEAD_JIRA_OPS }).map((op) => {
+        const key = (0, jira_db_1.getLinkByIssueId)(handle.db, op.jiraIssueId)?.jiraKey ?? op.jiraIssueId;
+        return {
+            id: (0, domain_1.inboxItemId)(handle.project.id, 'jira', String(op.id)),
+            projectId: handle.project.id,
+            projectName: handle.project.name,
+            kind: 'jira',
+            title: `${key} · ${op.opType}`,
+            detail: (0, domain_1.oneLine)(op.deadReason ?? op.lastError),
+            at: (0, domain_1.toIso)(op.updatedAt, nowIso),
+            version: `dead:${op.attempts}:${op.updatedAt}`,
+            action: 'retry-jira',
+            subjectId: String(op.id),
+            conversationId: null,
+            diagnosis: null,
+        };
+    });
+}
+/**
+ * A spend cap that is reached right now (daily, weekly or monthly; project or
+ * app-wide). The item stays while the cap is exhausted and leaves on its own
+ * once it is raised or the period rolls over; its version includes both, so a
+ * dismissal never hides the next period's crossing.
+ */
+function capItems(handle, nowIso) {
+    const caps = handle.caps?.() ?? [];
+    return caps.filter((cap) => cap.exhausted).map((cap) => ({
+        id: (0, domain_1.inboxItemId)(handle.project.id, 'budget', `cap-${cap.scope}-${cap.period}`),
+        projectId: handle.project.id,
+        projectName: handle.project.name,
+        kind: 'budget',
+        title: `${cap.scope === 'project' ? 'Project' : 'App-wide'} ${cap.period === 'day' ? 'daily' : cap.period === 'week' ? 'weekly' : 'monthly'} budget reached`,
+        detail: null,
+        at: nowIso,
+        version: `cap:${cap.budgetUsd}:${cap.resetsAt}`,
+        action: 'raise-cap',
+        subjectId: `${cap.scope}:${cap.period}`,
+        conversationId: null,
+        diagnosis: null,
+        cap: { scope: cap.scope, period: cap.period, budgetUsd: cap.budgetUsd, spentUsd: cap.spentUsd, resetsAt: cap.resetsAt },
+    }));
+}
+/** Run ids that recent deliveries already account for (the delivery speaks for them). */
+function representedRuns(db) {
+    const ids = new Set();
+    const rows = db.prepare(`SELECT run_ids FROM rail_pr_deliveries WHERE run_ids != '[]' ORDER BY created_at DESC LIMIT 500`).all();
+    for (const row of rows)
+        for (const id of parseJsonArray(row.run_ids))
+            if (typeof id === 'string')
+                ids.add(id);
+    return ids;
+}
+/**
+ * Bind the inbox sources to ONE project's own database. Each source is
+ * isolated: a missing table or a corrupt row costs that source, not the rest.
+ */
+function createProjectInboxSource(handle, now = Date.now) {
+    return {
+        projectId: handle.project.id,
+        projectName: handle.project.name,
+        collect() {
+            const nowMs = now();
+            const nowIso = new Date(nowMs).toISOString();
+            const items = [];
+            const guard = (label, fn) => {
+                try {
+                    items.push(...fn());
+                }
+                catch (err) {
+                    console.warn(`[inbox] ${handle.project.id} ${label} unavailable:`, err instanceof Error ? err.message : err);
+                }
+            };
+            let represented = new Set();
+            guard('deliveries', () => deliveryItems(handle, (0, rail_pr_store_1.listActivePrDeliveries)(handle.db), nowIso));
+            try {
+                represented = representedRuns(handle.db);
+            }
+            catch { /* runs then show without a delivery link */ }
+            guard('runs', () => runItems(handle, represented, nowIso, nowMs));
+            guard('jira', () => jiraItems(handle, nowIso));
+            guard('caps', () => capItems(handle, nowIso));
+            return items;
+        },
+    };
+}

package/server/dist/modules/inbox/application.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectInbox = collectInbox;
+const domain_1 = require("./domain");
+/**
+ * Project the inbox: ask each project's own source, isolate failures (one
+ * broken project never hides the others), cap each project and order newest
+ * first. Nothing is cached; every call reads current state.
+ */
+function collectInbox(sources, now = () => new Date()) {
+    const items = [];
+    const projects = [];
+    for (const source of sources) {
+        let own = [];
+        try {
+            own = source.collect();
+        }
+        catch (err) {
+            console.warn(`[inbox] ${source.projectId} unavailable (skipped):`, err instanceof Error ? err.message : err);
+        }
+        // A source can only speak for its own project.
+        const scoped = own.filter((item) => item.projectId === source.projectId).sort(domain_1.compareInboxItems).slice(0, domain_1.MAX_ITEMS_PER_PROJECT);
+        items.push(...scoped);
+        projects.push({ projectId: source.projectId, projectName: source.projectName, count: scoped.length });
+    }
+    items.sort(domain_1.compareInboxItems);
+    return { items, projects, generatedAt: now().toISOString() };
+}

package/server/dist/modules/inbox/domain.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * "Needs you" inbox: pure vocabulary. The inbox is a read-model projected from
+ * state other capabilities already own (deliveries, loop runs, the Jira
+ * outbox); it has no store of its own. Dismissal (Snooze / Done) is a
+ * per-viewer concern of the client and never reaches the server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ITEMS_PER_PROJECT = exports.INBOX_ACTIONS = exports.INBOX_KINDS = void 0;
+exports.inboxItemId = inboxItemId;
+exports.compareInboxItems = compareInboxItems;
+exports.oneLine = oneLine;
+exports.toIso = toIso;
+exports.INBOX_KINDS = ['review', 'question', 'failed', 'blocked', 'budget', 'jira'];
+/** What the primary inline action does (the client maps each to the existing handler/route). */
+exports.INBOX_ACTIONS = ['open-review', 'open-run', 'resume-run', 'retry-jira', 'raise-cap'];
+exports.MAX_ITEMS_PER_PROJECT = 50;
+function inboxItemId(projectId, kind, sourceId) {
+    return `${projectId}:${kind}:${sourceId}`;
+}
+/** Newest first; ties broken by id so the order is deterministic. */
+function compareInboxItems(a, b) {
+    const delta = Date.parse(b.at) - Date.parse(a.at);
+    if (Number.isFinite(delta) && delta !== 0)
+        return delta;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** Bound a free-text fragment to a single short line. */
+function oneLine(value, max = 140) {
+    if (!value)
+        return null;
+    const flat = value.replace(/\s+/g, ' ').trim();
+    if (!flat)
+        return null;
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/** SQLite `datetime('now')` is UTC without a zone: make it ISO so clients parse it right. */
+function toIso(value, fallback) {
+    if (!value)
+        return fallback;
+    const normalized = /[zZ]|[+-]\d{2}:?\d{2}$/.test(value) ? value : `${value.replace(' ', 'T')}Z`;
+    return Number.isNaN(Date.parse(normalized)) ? fallback : new Date(normalized).toISOString();
+}

package/server/dist/modules/inbox/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inboxItemId = exports.compareInboxItems = exports.INBOX_KINDS = exports.INBOX_ACTIONS = exports.collectInbox = void 0;
+var application_1 = require("./application");
+Object.defineProperty(exports, "collectInbox", { enumerable: true, get: function () { return application_1.collectInbox; } });
+var domain_1 = require("./domain");
+Object.defineProperty(exports, "INBOX_ACTIONS", { enumerable: true, get: function () { return domain_1.INBOX_ACTIONS; } });
+Object.defineProperty(exports, "INBOX_KINDS", { enumerable: true, get: function () { return domain_1.INBOX_KINDS; } });
+Object.defineProperty(exports, "compareInboxItems", { enumerable: true, get: function () { return domain_1.compareInboxItems; } });
+Object.defineProperty(exports, "inboxItemId", { enumerable: true, get: function () { return domain_1.inboxItemId; } });

package/server/dist/modules/inbox/ports.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/server/dist/modules/loops/runtime/loop-definition-run.js

@@ -15,6 +15,12 @@ async function runDefinitionLoop(request, runId, ports) {
         if (result.runtimeStatus !== 'paused')
             return result;
         const pending = result.pendingInterrupts ?? [];
+        if (!pending.length && result.pause && ports.awaitHostPause) {
+            if ((await ports.awaitHostPause(result.pause)) === 'stop' || ports.isCancelled())
+                return { ...result, runtimeStatus: 'cancelled', failed: true };
+            continuation = { resume: true };
+            continue;
+        }
         const reason = result.pendingQuestion?.question ?? result.pendingApproval?.reason ?? pending.map(item => {
             const value = item.value;
             return `${item.nodePath}: ${typeof value?.prompt === 'string' ? value.prompt : item.kind}`;
@@ -32,5 +38,8 @@ async function runDefinitionLoop(request, runId, ports) {
         continuation = selected.kind === 'question'
             ? { resume: true, answer: decision.text, interruptId: selected.id }
             : { resume: true, approve: [selected.id], interruptId: selected.id };
+        if (ports.beforeContinuation && (await ports.beforeContinuation()) === 'stop' || ports.isCancelled()) {
+            return { ...result, runtimeStatus: 'cancelled', failed: true };
+        }
     }
 }

package/server/dist/modules/loops/runtime/loop-definition.js

@@ -4,7 +4,7 @@ exports.compileLoopToDefinition = compileLoopToDefinition;
 const loop_command_catalog_1 = require("./loop-command-catalog");
 const loop_constants_1 = require("./loop-constants");
 const loop_graph_1 = require("./loop-graph");
-const AI_KINDS = new Set(['prompt', 'role-turn', 'decider', 'implementation', 'implementation-step']);
+const AI_KINDS = new Set(['prompt', 'role-turn', 'decider', 'implementation', 'implementation-step', 'derive-change']);
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 /** No I/O, model call, hash implementation or scheduling belongs in this adapter. */
 function compileLoopToDefinition(graph, launch) {
@@ -98,6 +98,9 @@ function compileLoopToDefinition(graph, launch) {
                     roleIds.add(role);
             if ((kind === 'role-turn' || kind === 'decider') && typeof params.roleId === 'string')
                 roleIds.add(params.roleId);
+            // Core's derive-change piece always invokes the built-in `deriver` role.
+            if (kind === 'derive-change')
+                roleIds.add('deriver');
             if (kind === 'end' && params.outcome === 'success' && params.requiresVerified === undefined)
                 params.requiresVerified = writes;
             const ends = Object.fromEntries(body.edges.filter((edge) => edge.source === node.id).map((edge) => [edge.label, edge.target]));
@@ -208,7 +211,7 @@ function pieceWrites(node, roles) {
         return params.access !== 'read';
     if (kind === 'role-turn')
         return (roles ?? {})[String(params.roleId)]?.access !== 'read';
-    return ['verify', 'shell', 'openspec-archive', 'implementation', 'implementation-step'].includes(kind ?? '');
+    return ['verify', 'shell', 'openspec-archive', 'implementation', 'implementation-step', 'derive-change'].includes(kind ?? '');
 }
 /** Expand templates once. Text inserted by spec/constants cannot introduce another token. */
 function resolveValue(value, launch, provider) {

package/server/dist/modules/loops/runtime/loop-executors.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.flowChangeHolder = flowChangeHolder;
+exports.flowDerivationChangeId = flowDerivationChangeId;
+exports.writeFlowSummary = writeFlowSummary;
 exports.createLoopExecutors = createLoopExecutors;
 /**
  * Production executors for the LoopRunManager. Thin glue that wires the engine's
@@ -23,6 +26,7 @@ const node_path_1 = require("node:path");
 const win_spawn_1 = require("../../../util/win-spawn");
 const providers_1 = require("../../../providers");
 const registry_1 = require("../../../providers/registry");
+const registry_2 = require("../../../providers/registry");
 const workspace_manager_1 = require("../../../workspace-manager");
 const claude_trust_1 = require("../../../claude-trust");
 const spawn_lifecycle_1 = require("../../execution/runtime/spawn-lifecycle");
@@ -30,6 +34,7 @@ const result_event_1 = require("../../accounting/runtime/result-event");
 const terminal_result_1 = require("../../../providers/terminal-result");
 const claude_background_tasks_1 = require("../../../providers/claude-background-tasks");
 const loop_constants_1 = require("./loop-constants");
+const loop_flow_spec_recipe_1 = require("./loop-flow-spec-recipe");
 const loop_decider_1 = require("./loop-decider");
 const rail_isolation_1 = require("../../delivery/runtime/rail-isolation");
 const repo_map_1 = require("../../../repo-map");
@@ -150,8 +155,66 @@ function aiStepExtraArgs(adapter, cwd, repoDir, manifest) {
     const args = (0, runtime_1.buildProviderRepoAccessArgs)(adapter, [...new Set([repoDir, ...(manifest?.repositories.map((repo) => repo.worktreePath) ?? []), ...(adapter.id === 'codex' ? [cwd] : [])])]);
     return args.length > 0 ? args : undefined;
 }
+/**
+ * Flow -> Spec: the bounded conversation summary Core's derive-change piece
+ * reads (`summaryPath`, relative to `.specrails/pipeline/<runId>/`). Written
+ * once, atomically, never through a symlink; a retry of the same run keeps
+ * the first file. Oversized input is truncated at the byte bound (the builder
+ * already bounds it; this is the last line of defence).
+ */
+/** Who holds `openspec/changes/<id>` in a Flow worktree (see FlowChangeIdHolder). Read-only. */
+function flowChangeHolder(cwd, baseSha, id) {
+    const changes = (0, node_path_1.join)(cwd, 'openspec', 'changes');
+    try {
+        const archive = (0, node_path_1.join)(changes, 'archive');
+        if ((0, node_fs_1.existsSync)(archive) && (0, node_fs_1.readdirSync)(archive).some((name) => name === id || name.endsWith(`-${id}`)))
+            return 'taken';
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(changes, id)))
+            return 'free';
+        if (!baseSha)
+            return 'taken';
+        // Present at the Flow base: someone else's change. Absent there: this Flow's own earlier derivation.
+        (0, node_child_process_1.execFileSync)('git', ['cat-file', '-e', `${baseSha}:openspec/changes/${id}`], { cwd, stdio: 'ignore', timeout: 5_000, windowsHide: true });
+        return 'taken';
+    }
+    catch {
+        return (0, node_fs_1.existsSync)((0, node_path_1.join)(changes, id)) ? 'own' : 'free';
+    }
+}
+/**
+ * The change a Flow -> Spec run derives: the Flow's own earlier change when it
+ * is still active in the worktree and absent at the Flow base (re-derived in
+ * place, whatever its name — legacy `ticket-<n>-addenda-…` included);
+ * otherwise a new one named after the spec title.
+ */
+function flowDerivationChangeId(cwd, flow, title) {
+    const own = flow.changeId;
+    if (own && /^[a-z0-9][a-z0-9._-]{0,127}$/i.test(own) && !own.includes('..') && own !== 'archive' && flowChangeHolder(cwd, flow.baseSha, own) === 'own')
+        return own;
+    return (0, loop_flow_spec_recipe_1.flowChangeId)(title, (id) => flowChangeHolder(cwd, flow.baseSha, id));
+}
+function writeFlowSummary(pipelineDir, summary) {
+    const file = (0, node_path_1.join)(pipelineDir, loop_flow_spec_recipe_1.FLOW_SUMMARY_FILE);
+    if ((0, node_fs_1.lstatSync)(file, { throwIfNoEntry: false }))
+        return;
+    let body = Buffer.from(summary, 'utf8');
+    if (body.length > loop_flow_spec_recipe_1.FLOW_SUMMARY_LIMIT_BYTES)
+        body = Buffer.from(body.subarray(0, loop_flow_spec_recipe_1.FLOW_SUMMARY_LIMIT_BYTES).toString('utf8').replace(/\uFFFD+$/, ''), 'utf8');
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        (0, node_fs_1.writeFileSync)(temp, body, { flag: 'wx', mode: 0o600 });
+        (0, node_fs_1.renameSync)(temp, file);
+    }
+    finally {
+        (0, node_fs_1.rmSync)(temp, { force: true });
+    }
+}
 function createLoopExecutors(opts = {}) {
-    const resolveEnv = () => typeof opts.env === 'function' ? opts.env() : opts.env ?? process.env;
+    // Core-hosted work may launch any configured role provider, so it receives
+    // every registered adapter's names; plain AI steps and deciders receive only
+    // their provider's; shell steps receive none.
+    const coreProviderAllowlist = () => (0, runtime_1.providerEnvAllowlist)((0, registry_1.listAdapters)());
+    const resolveEnv = (providerAllowlist) => typeof opts.env === 'function' ? opts.env(providerAllowlist ?? coreProviderAllowlist()) : opts.env ?? process.env;
     const inactivityTimeoutMs = () => {
         const env = resolveEnv();
         const configuredIdle = env.SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS ?? process.env.SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS;
@@ -186,6 +249,11 @@ function createLoopExecutors(opts = {}) {
             const host = (0, agent_runtime_bridge_1.readFrozenRuntimeHost)(contextPath, resolveEnv(), runId);
             await (0, agent_runtime_bridge_1.runAgentRuntimeControl)({ kind: 'cancel', runId, contextPath, requestId, ...host });
         },
+        async pauseDefinition({ runId, contextPath, requestId, reason }) {
+            const host = (0, agent_runtime_bridge_1.readFrozenRuntimeHost)(contextPath, resolveEnv(), runId);
+            const paused = await (0, agent_runtime_bridge_1.runAgentRuntimeControl)({ kind: 'pause', runId, contextPath, requestId, reason, ...host });
+            return { outcome: paused.outcome };
+        },
         async assertDefinitionSupport(graph) {
             const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
             if (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1)
@@ -194,6 +262,10 @@ function createLoopExecutors(opts = {}) {
                 if (runtime.api?.capabilities?.workflowAgentSteps !== 1)
                     throw new Error('engine_unsupported: Update Core to run configurable workflow agent steps');
             }
+            if (graph && [graph, ...Object.values(graph.components ?? {})].some(body => body.nodes.some(node => node.data?.kind === 'derive-change'))) {
+                if (runtime.api?.capabilities?.deriveChange !== 1)
+                    throw new Error('engine_unsupported: Update Core to run the Flow → Spec derive-change step');
+            }
             if (graph && [graph, ...Object.values(graph.components ?? {})].some(body => body.nodes.some(node => node.data?.kind === 'implementation-step'))) {
                 if (runtime.api?.capabilities?.implementationSteps !== 1)
                     throw new Error('engine_unsupported: Update Core to run independent implementation steps');
@@ -221,17 +293,26 @@ function createLoopExecutors(opts = {}) {
                 const result = await (0, agent_runtime_bridge_1.runAgentRuntimeInvocation)({ contextPath, ...host, engineVersion: 2, resume: true, answer: input.answer, approve: input.approve, recover: input.recover, interruptId: input.interruptId, onLine: input.onLine, onRuntimeEvent: input.onRuntimeEvent, onSpawn: input.onSpawn, timeoutMs: input.timeoutMs });
                 return { ...result, runtimeStatus: result.runtimeStatus ?? 'failed' };
             }
-            const seeded = (0, loop_run_manager_1.seedChangeId)({ ...request, runId });
+            // Flow -> Spec derives ONE change for code that already exists: it is named
+            // after the spec title (never addenda), and no delta briefing applies.
+            const seeded = request.flowDerivation
+                ? { id: flowDerivationChangeId(request.cwd, request.flowDerivation, request.spec?.title), source: 'flow' }
+                : (0, loop_run_manager_1.seedChangeId)({ ...request, runId });
             const delta = seeded && (seeded.source === 'addenda' || seeded.source === 'revision')
                 ? `DELTA OPENSPEC TARGET: ${seeded.id}. Use ONLY openspec/changes/${seeded.id}/; create it if missing. Inspect the current branch before planning. For delivered work, plan and implement ONLY the attached addenda or delivery change request, preserving existing behavior outside the delta. For work not yet implemented, implement the full spec together with its addenda. Map each requested change to acceptance checks. Do not redo or archive the original proposal. Report each addendum id with concrete files and test evidence.`
                 : undefined;
             const briefing = [delta, request.constants?.REVISION_REQUEST, request.followUp?.briefing, request.addenda?.briefing].filter(Boolean).join('\n\n');
             const spec = request.spec && briefing ? { ...request.spec, description: [request.spec.description, briefing].filter(Boolean).join('\n\n'), ...(request.spec.tickets ? { tickets: request.spec.tickets.map(ticket => ({ ...ticket, description: [ticket.description, briefing].filter(Boolean).join('\n\n') })) } : {}) } : request.spec;
             const env = { ...programmaticStepEnv(resolveEnv(), request.repoDir, request.executionManifest), SPECRAILS_GIT_AUTO: 'false' };
-            const core = (0, core_execution_1.prepareCoreExecution)({ run: { runId, projectId: request.projectId, repositoryId: request.repositoryId, spec, goal: request.spec?.title ?? request.loopName }, cwd: request.cwd, repoDir: request.repoDir, manifest: request.executionManifest, env, sourcePath: request.executionManifest ? undefined : opts.sourcePath?.(), workspacePaths: request.executionManifest ? undefined : opts.workspacePaths?.(), selectedWorkspacePaths: request.workspacePaths });
+            const core = (0, core_execution_1.prepareCoreExecution)({ run: { runId, projectId: request.projectId, repositoryId: request.repositoryId, spec, goal: request.spec?.title ?? request.loopName }, cwd: request.cwd, repoDir: request.repoDir, manifest: request.executionManifest, env, sourcePath: request.executionManifest ? undefined : opts.sourcePath?.(), workspacePaths: request.executionManifest ? undefined : opts.workspacePaths?.(), selectedWorkspacePaths: request.workspacePaths,
+                // Flow -> Spec: Core measures the change from the Flow's reservation commit.
+                ...(request.flowDerivation?.baseSha ? { repositoryBaseSha: request.flowDerivation.baseSha } : {}) });
+            if (request.flowDerivation)
+                writeFlowSummary((0, node_path_1.dirname)(core.contextPath), request.flowDerivation.summary);
             const result = await (0, agent_runtime_bridge_1.runAgentRuntimeInvocation)({
                 contextPath: core.contextPath, cwd: request.cwd, env: core.env,
                 configPath: runtimeConfigPath(request.cwd), engineVersion: 2,
+                projectRuntime: opts.projectRuntime?.(),
                 loopConfig: request.graph.config.agents,
                 change: seeded?.id ?? (0, agent_runtime_bridge_1.runtimeChangeName)(runId),
                 resume: input.resume, answer: input.answer, approve: input.approve, interruptId: input.interruptId,
@@ -309,7 +390,7 @@ function createLoopExecutors(opts = {}) {
             // for the pipeline's I/O exactly like QueueManager: SPECRAILS_REPO_DIR +
             // claude `--add-dir <repoDir>` (see the shared helpers above). Best-effort
             // agent self-heal on Windows.
-            const baseEnv = resolveEnv();
+            const baseEnv = resolveEnv(coreRun ? undefined : (0, runtime_1.providerEnvAllowlist)(adapter));
             const existingContext = coreRun ? runtimeContextPath(cwd, coreRun.runId, baseEnv) : undefined;
             const programmatic = coreRun && existingContext && (coreRun.implementation || (coreRun.verificationStep && existsRuntimeRequest(existingContext)));
             const baseStepEnv = programmatic ? programmaticStepEnv(baseEnv, repoDir, executionManifest) : withProfileEnv(aiStepEnv(baseEnv, repoDir, executionManifest), provider, profileName);
@@ -322,7 +403,7 @@ function createLoopExecutors(opts = {}) {
                 // never silently replay an interrupted mutating phase.
                 return (0, agent_runtime_bridge_1.runAgentRuntimeInvocation)({
                     contextPath: core.contextPath, cwd, env: { ...programmaticStepEnv(resolveEnv(), repoDir, executionManifest), SPECRAILS_EXECUTION_CONTEXT: core.contextPath }, configPath: runtimeConfigPath(cwd),
-                    change: (0, agent_runtime_bridge_1.runtimeChangeName)(coreRun.runId), resume: admitted,
+                    change: (0, agent_runtime_bridge_1.runtimeChangeName)(coreRun.runId), resume: admitted, projectRuntime: opts.projectRuntime?.(),
                     defaultProvider: provider, providerOverride: runtimeProviderOverride,
                     onLine, onRawLine, onSpawn, timeoutMs: aiStepTimeoutMs,
                 });
@@ -339,7 +420,7 @@ function createLoopExecutors(opts = {}) {
             const effectivePrompt = (0, runtime_1.formatProviderCommand)(adapter, [core?.promptPrefix, prompt].filter(Boolean).join('\n\n'), cwd, sessionId ?? undefined);
             const buildOpts = {
                 prompt: effectivePrompt,
-                ...(adapter.id === 'claude' || (0, registry_1.isLocalAdapterId)(adapter.id) ? { systemPrompt: loop_constants_1.FOREGROUND_RULE } : {}),
+                ...(adapter.id === 'claude' || (0, registry_2.isLocalAdapterId)(adapter.id) ? { systemPrompt: loop_constants_1.FOREGROUND_RULE } : {}),
                 model,
                 sessionId: sessionId ?? undefined,
                 reasoning_effort: effort,
@@ -550,7 +631,7 @@ function createLoopExecutors(opts = {}) {
             const adapter = (0, providers_1.getAdapter)(provider);
             if (!adapter.capabilities.persistentStdin)
                 return null;
-            const baseStepEnv = withProfileEnv(aiStepEnv(resolveEnv(), repoDir, executionManifest), provider, profileName);
+            const baseStepEnv = withProfileEnv(aiStepEnv(resolveEnv(coreRun ? undefined : (0, runtime_1.providerEnvAllowlist)(adapter)), repoDir, executionManifest), provider, profileName);
             const core = coreRun ? (0, core_execution_1.prepareCoreExecution)({ run: coreRun, cwd, repoDir, manifest: executionManifest, env: baseStepEnv, sourcePath: executionManifest ? undefined : opts.sourcePath?.(), workspacePaths: executionManifest ? undefined : opts.workspacePaths?.(), selectedWorkspacePaths: coreRun?.workspacePaths }) : undefined;
             const stepEnv = core?.env ?? baseStepEnv;
             const extraArgs = aiStepExtraArgs(adapter, cwd, repoDir, executionManifest);
@@ -613,14 +694,14 @@ function createLoopExecutors(opts = {}) {
             return (0, core_execution_1.checkCoreCompletion)(core.contextPath, cwd, env, coreRun.runId);
         },
         async runShell({ command, cwd, repoDir, onLine, onSpawn, timeoutMs }) {
-            const env = resolveEnv();
+            const env = resolveEnv([]);
             return runShellCommand(command, repoDir ?? cwd, repoDir ? { ...env, SPECRAILS_REPO_DIR: repoDir } : env, timeoutMs ?? SHELL_TIMEOUT_MS, onLine, onSpawn);
         },
         async runDecider({ systemPrompt, userPrompt, provider, model, effort, cwd, repoDir, executionManifest, onRawLine, onSpawn, timeoutMs }) {
             const adapter = (0, providers_1.getAdapter)(provider);
             let text = '';
             let errorText;
-            const baseEnv = resolveEnv();
+            const baseEnv = resolveEnv((0, runtime_1.providerEnvAllowlist)(adapter));
             const decEnv = aiStepEnv(baseEnv, repoDir, executionManifest);
             // spec-gen is a one-shot, system-prompted invocation (workspace-write on
             // codex, not full-access) — appropriate for a read-only judgment.