specrails-desktop 2.57.1 → 2.58.0

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

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_DECIDER_ROLE = void 0;
+exports.convertLegacyLoop = convertLegacyLoop;
+const loop_graph_1 = require("./loop-graph");
+const reserved = new Set(['START', 'END', '__start__', '__end__', 'next', 'constructor', 'prototype']);
+const safeId = (id) => /^[A-Za-z0-9][A-Za-z0-9_-]{0,119}$/.test(id) && !reserved.has(id);
+const PASS = 'compatPassFailed', ITERATION = 'compatIteration', STEPS = 'compatSteps';
+exports.LEGACY_DECIDER_ROLE = 'legacy-loop-decider';
+/** Pure projection only: no settings, database writes, provider calls or publication.
+ * The caller validates the result against its selected Core before saving it. */
+function convertLegacyLoop(graph, bindings = {}) {
+    const validation = (0, loop_graph_1.validateLoopGraph)(graph);
+    if (!validation.valid)
+        return { ok: false, issues: validation.errors.map(error => ({ code: error.code, message: error.message, ...(error.nodeId ? { nodeId: error.nodeId } : {}) })) };
+    if ((0, loop_graph_1.isDefinitionGraph)(graph))
+        return { ok: false, issues: [{ code: 'already_core', message: 'This graph already uses Core pieces.' }] };
+    try {
+        (0, loop_graph_1.assertLoopFailureRecovery)(graph);
+    }
+    catch (error) {
+        return { ok: false, issues: [{ code: 'invalid_recovery', message: String(error) }] };
+    }
+    const issues = [];
+    for (const node of graph.nodes) {
+        if (node.type === 'shell' && !node.data?.repositoryId && !bindings.repositoryId)
+            issues.push({ code: 'repository_binding_required', nodeId: node.id, message: 'Select the original shell repository before converting this graph.' });
+        if (node.type === 'shell' && Array.isArray(node.data?.requireRunVars) && node.data.requireRunVars.some(name => typeof name !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name)))
+            issues.push({ code: 'invalid_run_variable', nodeId: node.id, message: 'Required runtime variables must use Core variable names.' });
+    }
+    if (issues.length)
+        return { ok: false, issues };
+    const used = new Set(graph.nodes.filter(node => safeId(node.id)).map(node => node.id));
+    const fresh = (hint) => {
+        const base = ('compat-' + hint.replace(/[^A-Za-z0-9_-]/g, '-')).slice(0, 100);
+        let id = base, suffix = 0;
+        while (used.has(id))
+            id = `${base}-${++suffix}`;
+        used.add(id);
+        return id;
+    };
+    const nodeIds = Object.fromEntries(graph.nodes.map((node, index) => [node.id, safeId(node.id) ? node.id : fresh('node-' + index)]));
+    const start = graph.nodes.find(node => node.type === 'start');
+    const nodes = [{ ...structuredClone(start), id: nodeIds[start.id] }], edges = [];
+    const emit = (id, kind, params, ends, original) => {
+        nodes.push({ id, type: 'core', position: original?.position ? { ...original.position } : { x: 480, y: nodes.length * 120 }, data: { kind, params, retry: { maxAttempts: 1 }, ...(original?.data?.label ? { label: original.data.label } : {}) } });
+        for (const [label, target] of Object.entries(ends))
+            edges.push({ id: fresh('edge'), source: id, target, label });
+    };
+    const failure = fresh('failed'), exhausted = fresh('iteration-limit');
+    const end = (id, outcome, reason) => emit(id, 'end', { outcome, ...(reason ? { reason } : {}) }, {});
+    const assign = (id, params, target) => emit(id, 'assign', params, { next: target, failed: failure });
+    const condition = (id, expr, yes, no) => emit(id, 'condition', { expr }, { true: yes, false: no });
+    const entry = new Map();
+    const legacyCap = (graph.config.maxIterations + 1) * (graph.nodes.length + 2) + 16;
+    // Every original visit keeps its own legacy ceiling as well as Core's global
+    // control-transition ceiling. Free control nodes cannot buy another AI pass.
+    for (const node of graph.nodes.filter(node => node.type !== 'start')) {
+        const guard = fresh('visit'), count = fresh('visit-count');
+        entry.set(node.id, guard);
+        condition(guard, `$vars.${STEPS} < ${legacyCap}`, count, exhausted);
+        assign(count, { increment: { [STEPS]: 1 } }, nodeIds[node.id]);
+    }
+    if (graph.edges.some(edge => edge.target === start.id)) {
+        const guard = fresh('revisit-start'), count = fresh('revisit-start-count');
+        entry.set(start.id, guard);
+        condition(guard, `$vars.${STEPS} < ${legacyCap}`, count, exhausted);
+        assign(count, { increment: { [STEPS]: 1 } }, entry.get(graph.edges.find(edge => edge.source === start.id).target));
+    }
+    const successor = (node) => entry.get(graph.edges.find(edge => edge.source === node.id).target);
+    const recoveryVars = new Map(graph.nodes.filter(node => node.data?.failureRecovery).map((node, index) => [node.id, 'compatRecovery' + index]));
+    const writes = graph.nodes.some(node => node.type === 'ai-step' || node.type === 'shell');
+    let implementation = false;
+    const failedPass = (target) => {
+        const id = fresh('failed-pass');
+        assign(id, { set: { [PASS]: true } }, target);
+        return id;
+    };
+    const promptParams = (node, repair = false) => {
+        const text = repair
+            ? 'Repair ONLY the OpenSpec artifacts at openspec/changes/{{run.changeId}}/ using the validation diagnostics in history. Preserve requirements and acceptance criteria. Do not edit implementation code, run repository tests, archive, create a new change, or expand scope. {{const:GUARDRAILS}}'
+            : String(node.data?.prompt ?? '');
+        const verification = !repair && (node.data?.requireVerificationPass === true || /\{\{cmd:(?:verify|revision-verify|opsx:verify)\}\}/.test(text));
+        return { text: text || 'Continue the frozen workflow obligations.', access: 'write', sentinel: verification ? 'verification' : 'blocked',
+            sessionContinuity: node.data?.freshSession === true ? 'none' : 'run', appendHistory: true,
+            timeoutMs: Math.round((graph.config.aiStepTimeoutMinutes ?? 15) * 60_000), idleTimeoutMs: 30 * 60_000 };
+    };
+    const recover = (node) => {
+        const policy = node.data?.failureRecovery;
+        if (!policy)
+            return failure;
+        const guard = fresh('recovery-guard'), consume = fresh('recovery-count');
+        let target = entry.get(policy.target);
+        if (policy.target !== node.id || policy.artifactOnly) {
+            const repair = fresh('artifact-repair'), original = graph.nodes.find(item => item.id === policy.target);
+            target = fresh('repair-visit');
+            const count = fresh('repair-count');
+            condition(target, `$vars.${STEPS} < ${legacyCap}`, count, exhausted);
+            assign(count, { increment: { [STEPS]: 1 } }, repair);
+            emit(repair, 'prompt', promptParams(original, true), { next: entry.get(node.id), blocked: failure, failed: failure }, original);
+        }
+        condition(guard, `$vars.${recoveryVars.get(node.id)} < 1`, consume, failure);
+        assign(consume, { increment: { [recoveryVars.get(node.id)]: 1 } }, target);
+        return guard;
+    };
+    for (const node of graph.nodes) {
+        const id = nodeIds[node.id];
+        if (node.type === 'start')
+            continue;
+        if (node.type === 'end') {
+            if (node.data?.outcome === 'failure') {
+                end(id, 'failure');
+                continue;
+            }
+            const done = fresh('done');
+            condition(id, `$vars.${PASS} == false`, writes ? (() => { const verify = fresh('verify'); emit(verify, 'verify', { commands: 'configured' }, { pass: done, fail: failure, failed: failure }); return verify; })() : done, failure);
+            end(done, 'success');
+            continue;
+        }
+        if (node.type === 'condition') {
+            condition(id, 'true', successor(node), successor(node));
+            continue;
+        }
+        if (node.type === 'decider') {
+            const out = graph.edges.filter(edge => edge.source === node.id);
+            const branch = (name) => out.find(edge => edge.branch === name)?.target ?? out.find(edge => (graph.nodes.find(target => target.id === edge.target)?.type === 'end') === (name === 'stop')).target;
+            const cont = entry.get(branch('continue')), stop = entry.get(branch('stop'));
+            const evaluate = fresh('decision-count'), ordinary = fresh('continue-limit'), reset = fresh('new-pass'), route = fresh('decision-route');
+            // Redirect the visit counter into the decider's iteration admission.
+            edges.find(edge => edge.target === id).target = evaluate;
+            const ready = fresh('decision-ready');
+            condition(evaluate, `$vars.${ITERATION} < ${graph.config.maxIterations}`, ready, exhausted);
+            assign(ready, { increment: { [ITERATION]: 1 } }, id);
+            emit(id, 'decider', { roleId: exports.LEGACY_DECIDER_ROLE, goal: String(node.data?.goal ?? 'The loop goal is met.'), timeoutMs: 180_000, noProgress: 3, continueWhen: `$vars.${PASS} == true` }, { continue: route, stop, failed: failure }, node);
+            condition(route, `$outputs.${id}.blocked == true`, cont, ordinary);
+            condition(ordinary, `$vars.${ITERATION} < ${graph.config.maxIterations}`, reset, exhausted);
+            assign(reset, { set: { [PASS]: false } }, cont);
+            continue;
+        }
+        const next = successor(node), hardFailure = node.data?.stopOnFailure === true ? failure : failedPass(next);
+        if (node.type === 'ai-step') {
+            const raw = String(node.data?.prompt ?? '');
+            if (node.data?.operation === 'core-implementation' || /\{\{\s*cmd:(?:implement|batch)\s*\}\}/.test(raw) || /^\s*(?:\/specrails:|\/skill:specrails-|\$)(?:implement|batch-implement)(?:\s|$)/.test(raw)) {
+                implementation = true;
+                // The removed Batch command (`{{cmd:batch}}` / `batch-implement`) converts
+                // exactly like implement: one aggregate implementation node, no map/join.
+                emit(id, 'implementation', {}, { next, rejected: hardFailure, failed: hardFailure }, node);
+            }
+            else {
+                const params = promptParams(node);
+                emit(id, 'prompt', params, params.sentinel === 'verification'
+                    ? { pass: next, fail: node.data?.stopOnFailure === true ? recover(node) : hardFailure, failed: hardFailure }
+                    : { next, blocked: hardFailure, failed: hardFailure }, node);
+            }
+        }
+        else if (node.type === 'shell') {
+            const required = Array.isArray(node.data?.requireRunVars) ? node.data.requireRunVars : [];
+            let execute = id;
+            if (required.length) {
+                execute = fresh('shell');
+                condition(id, required.map(name => `exists($vars.${name}) && $vars.${name} != ""`).join(' && '), execute, failure);
+            }
+            let commandFailure = hardFailure;
+            const command = String(node.data?.command ?? '').trim();
+            const validate = /^openspec validate \{\{\s*run\.changeId\s*\}\} --type change --strict --no-interactive$/.test(command);
+            const archive = /^openspec archive \{\{\s*run\.changeId\s*\}\} -y$/.test(command);
+            if (validate || archive) {
+                const params = { change: '{{run.changeId}}', allowArchived: true, repositoryId: node.data?.repositoryId ?? bindings.repositoryId };
+                if (validate)
+                    emit(execute, 'openspec-validate', params, { pass: next, fail: node.data?.stopOnFailure === true ? recover(node) : hardFailure, failed: hardFailure }, node);
+                else {
+                    let failed = hardFailure;
+                    if (node.data?.stopOnFailure === true && node.data.failureRecovery) {
+                        failed = fresh('archive-recovery-exit');
+                        condition(failed, `$outputs.${execute}.exitCode == 1`, recover(node), hardFailure);
+                    }
+                    emit(execute, 'openspec-archive', params, { next, failed }, node);
+                }
+                continue;
+            }
+            if (node.data?.stopOnFailure === true && node.data.failureRecovery) {
+                commandFailure = fresh('recoverable-exit');
+                condition(commandFailure, `$outputs.${execute}.exitCode == 1`, recover(node), failure);
+            }
+            emit(execute, 'shell', { commandLine: command, repositoryId: node.data?.repositoryId ?? bindings.repositoryId,
+                timeoutMs: 600_000, outputCapBytes: 262_144 }, { ok: next, fail: commandFailure, failed: hardFailure }, node);
+        }
+    }
+    end(failure, 'failure', 'legacy_required_work_failed');
+    end(exhausted, 'failure', 'legacy_iteration_limit');
+    const initial = { [PASS]: false, [ITERATION]: 0, [STEPS]: 1, ...Object.fromEntries([...recoveryVars.values()].map(name => [name, 0])) };
+    const chunks = Object.entries(initial);
+    let first = successor(start);
+    while (chunks.length) {
+        const id = fresh('initialize');
+        assign(id, { set: Object.fromEntries(chunks.splice(-64)) }, first);
+        first = id;
+    }
+    edges.unshift({ id: fresh('start-edge'), source: nodeIds[start.id], target: first });
+    // Avoid unreachable synthetic terminals in graphs that never branch/fail.
+    const reachable = new Set(), pending = [nodeIds[start.id]];
+    while (pending.length) {
+        const current = pending.pop();
+        if (reachable.has(current))
+            continue;
+        reachable.add(current);
+        pending.push(...edges.filter(edge => edge.source === current).map(edge => edge.target));
+    }
+    const maxTransitions = implementation ? 10_000 : legacyCap * 12 + nodes.length;
+    if (maxTransitions > 10_000)
+        return { ok: false, issues: [{ code: 'transition_limit', message: 'This conversion exceeds Core’s 10000-transition ceiling; reduce the requested iteration bound.' }] };
+    const converted = { nodes: nodes.filter(node => reachable.has(node.id)), edges: edges.filter(edge => reachable.has(edge.source)),
+        config: { ...graph.config, policies: { ...graph.config.policies, failFast: Math.min(graph.config.policies?.failFast ?? 2, 2) }, maxTransitions, journal: implementation ? 'implementation' : 'ledger-only', change: graph.config.change ?? (implementation ? undefined : 'none'),
+            ...(graph.nodes.some(node => node.type === 'decider') ? { legacyDeciderRole: exports.LEGACY_DECIDER_ROLE } : {}) } };
+    const result = (0, loop_graph_1.validateLoopGraph)(converted);
+    if (!result.valid)
+        return { ok: false, issues: result.errors.map(error => ({ code: error.code, message: error.message, ...(error.nodeId ? { nodeId: error.nodeId } : {}) })) };
+    return { ok: true, graph: converted, nodeIds, issues: [] };
+}

package/server/dist/modules/loops/runtime/loop-core-factory.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coreFactoryGraph = coreFactoryGraph;
+/** App-owned definition graphs. Core supplies schemas, execution and canonical versions. */
+function coreFactoryGraph(mode) {
+    const nodes = [{ id: 'start', type: 'start', position: { x: 0, y: 0 } }];
+    const edges = [];
+    const config = { maxIterations: 12, maxTransitions: 120, timeoutMinutes: 0, aiStepTimeoutMinutes: 0,
+        journal: mode === 'implement' ? 'implementation' : 'ledger-only', change: mode === 'freestyle' ? 'none' : 'new' };
+    const node = (id, kind, params, outcomes) => {
+        nodes.push({ id, type: 'core', position: { x: 0, y: nodes.length * 120 }, data: { kind, params } });
+        for (const [label, target] of Object.entries(outcomes))
+            edges.push({ id: `e-${id}-${label}`, source: id, target, label });
+    };
+    const next = (id) => ({ next: id, failed: 'failed' });
+    const promptNext = (id) => ({ ...next(id), blocked: 'failed' });
+    const verify = (id, passed = 'done', failed = 'failed') => node(id, 'verify', { commands: 'configured' }, { pass: passed, fail: failed, failed: 'failed' });
+    let entry;
+    if (mode === 'implement') {
+        entry = 'implement';
+        node(entry, 'implementation', {}, { next: 'done', rejected: 'failed', failed: 'failed' });
+    }
+    else if (mode === 'quick-sdd') {
+        entry = 'prepare';
+        node('prepare', 'prompt', { nativeCommand: { id: 'opsx:ff', args: '{{run.changeId}}' }, access: 'write', sentinel: 'blocked' }, promptNext('validate'));
+        node('validate', 'openspec-validate', { change: '{{run.changeId}}' }, { pass: 'apply', fail: 'failed', failed: 'failed' });
+        node('apply', 'prompt', { nativeCommand: { id: 'opsx:apply', args: '{{run.changeId}}' }, access: 'write', sentinel: 'blocked' }, promptNext('check'));
+        verify('check', 'archive');
+        node('archive', 'openspec-archive', { change: '{{run.changeId}}' }, next('verify'));
+        verify('verify');
+    }
+    else {
+        entry = 'implement';
+        node('implement', 'prompt', { text: '{{cmd:freestyle}}', access: 'write', sentinel: 'blocked' }, promptNext('verify'));
+        verify('verify', 'decide', 'fix');
+        node('decide', 'decider', { roleId: 'loop-decider', goal: 'Stop only when actual behavioral evidence proves every frozen acceptance criterion is implemented across every selected ticket and repository. Passing baseline checks alone is insufficient.', noProgress: 3 }, { continue: 'fix', stop: 'done', failed: 'failed' });
+        node('fix', 'prompt', { text: '{{cmd:fix}}', access: 'write', sentinel: 'blocked' }, promptNext('verify'));
+    }
+    edges.unshift({ id: 'e-start', source: 'start', target: entry });
+    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 120 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 320, y: nodes.length * 120 }, data: { outcome: 'failure' } });
+    return { nodes, edges, config };
+}

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDefinitionResumeControls = validateDefinitionResumeControls;
+/** Resolve controls against the latest retained journal, never against UI labels or node paths. */
+function validateDefinitionResumeControls(value, probe) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Resume controls must be an object');
+    const body = value;
+    if (Object.keys(body).some(key => !['answer', 'interruptId', 'approve', 'recover'].includes(key)))
+        throw new Error('Unknown resume control');
+    if (body.answer !== undefined && (typeof body.answer !== 'string' || !body.answer.trim() || body.answer.length > 20_000))
+        throw new Error('Answer must be nonempty and contain at most 20000 characters');
+    if (body.interruptId !== undefined && (typeof body.interruptId !== 'string' || !body.interruptId))
+        throw new Error('An exact interrupt ID is required');
+    const ids = (key) => {
+        const values = body[key];
+        if (values === undefined)
+            return undefined;
+        if (!Array.isArray(values) || values.length > 10_000 || values.some(id => typeof id !== 'string' || !id) || new Set(values).size !== values.length)
+            throw new Error(`${key} must contain unique IDs`);
+        return values;
+    };
+    const approve = ids('approve'), recover = ids('recover');
+    if (body.answer !== undefined && approve?.length)
+        throw new Error('Submit an answer or approvals separately');
+    const pending = probe.pendingInterrupts;
+    if (approve?.some(id => !pending.some(item => item.id === id && (item.kind === 'approval' || item.kind === 'gate'))))
+        throw new Error('Approval is no longer pending');
+    if (recover?.some(id => !probe.recoverableSteps.some(item => item.attemptId === id)))
+        throw new Error('Recovery requires an exact recoverable attempt ID');
+    let interruptId = body.interruptId;
+    if (body.answer !== undefined && !interruptId) {
+        const questions = pending.filter(item => item.kind === 'question');
+        if (questions.length !== 1)
+            throw new Error('Select an exact pending question');
+        interruptId = questions[0].id;
+    }
+    if (interruptId && !pending.some(item => item.id === interruptId))
+        throw new Error('Interrupt is no longer pending');
+    if (body.answer !== undefined && !pending.some(item => item.id === interruptId && item.kind === 'question'))
+        throw new Error('Answers require a pending question');
+    if (interruptId && body.answer === undefined && !approve?.includes(interruptId))
+        throw new Error('Select an answer or approval for the interrupt');
+    return {
+        ...(body.answer === undefined ? {} : { answer: body.answer }),
+        ...(interruptId ? { interruptId } : {}), ...(approve ? { approve } : {}), ...(recover ? { recover } : {}),
+    };
+}

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

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDefinitionUsage = readDefinitionUsage;
+exports.createDefinitionEventProjection = createDefinitionEventProjection;
+const db_1 = require("../../../db");
+const ai_invocations_1 = require("../../accounting/runtime/ai-invocations");
+const distribute_int_1 = require("../../../util/distribute-int");
+const loop_runs_store_1 = require("./loop-runs-store");
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
+const number = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+const timestamp = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value)) ? value : undefined;
+const canonical = (value) => Array.isArray(value) ? value.map(canonical) : object(value)
+    ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)])) : value;
+function readDefinitionUsage(db, runId) {
+    const row = db.prepare(`SELECT COUNT(*) AS count, COALESCE(SUM(total_cost_usd),0) AS cost,
+    COALESCE(SUM(tokens_in),0) AS tokensIn, COALESCE(SUM(tokens_out),0) AS tokensOut,
+    COALESCE(SUM(tokens_cache_read),0) AS cacheRead, COALESCE(SUM(tokens_cache_create),0) AS cacheCreate,
+    COALESCE(SUM(duration_ms),0) AS duration, COALESCE(SUM(num_turns),0) AS turns,
+    MAX(total_cost_usd IS NULL) AS costUnknown, MAX(tokens_in IS NULL) AS tokensInUnknown, MAX(tokens_out IS NULL) AS tokensOutUnknown,
+    MAX(tokens_cache_read IS NULL) AS cacheReadUnknown, MAX(tokens_cache_create IS NULL) AS cacheCreateUnknown, MAX(num_turns IS NULL) AS turnsUnknown
+    FROM ai_invocations WHERE surface='loop' AND loop_run_id=?`).get(runId);
+    return { ...row, present: row.count > 0, costUnknown: Boolean(row.costUnknown), tokensInUnknown: Boolean(row.tokensInUnknown), tokensOutUnknown: Boolean(row.tokensOutUnknown), cacheReadUnknown: Boolean(row.cacheReadUnknown), cacheCreateUnknown: Boolean(row.cacheCreateUnknown), turnsUnknown: Boolean(row.turnsUnknown) };
+}
+/** Project committed Core events. The event marker and physical usage share one Desktop transaction. */
+function createDefinitionEventProjection(input) {
+    const { db, runId } = input;
+    let count = Number(db.prepare("SELECT COALESCE(MAX(json_extract(payload,'$.index')),0) AS count FROM events WHERE job_id=? AND event_type='loop_step'").get(runId).count);
+    // Only a new physical invocation changes usage. Publish the cached aggregate
+    // after commit so a failed event transaction cannot poison later progress.
+    let totals = readDefinitionUsage(db, runId);
+    return (event) => {
+        const workflow = event.type === 'workflow-event' && object(event.event) ? event.event : undefined;
+        const durableId = workflow ? text(workflow.id) : text(event.eventId);
+        const owner = workflow?.runId ?? event.runId;
+        if (owner !== undefined && owner !== runId)
+            throw new Error('Core event belongs to another run');
+        const encoded = JSON.stringify(event);
+        const at = timestamp(workflow?.timestamp ?? event.timestamp) ?? new Date().toISOString();
+        const outgoing = [];
+        let nextCount = count;
+        let nextTotals = totals;
+        const persist = (eventType, payload) => {
+            const seq = input.nextSequence(), json = JSON.stringify(payload);
+            (0, db_1.appendEvent)(db, runId, seq, { event_type: eventType, source: 'stdout', payload: json });
+            outgoing.push({ eventType, payload: json, seq, timestamp: at });
+        };
+        db.transaction(() => {
+            if (durableId) {
+                const sequence = workflow?.sequence ?? event.sequence;
+                if (owner !== runId || !Number.isSafeInteger(sequence) || sequence < 1 || durableId !== `${runId}:${sequence}`)
+                    throw new Error('Malformed durable Core event identity');
+                const prior = db.prepare("SELECT payload FROM events WHERE job_id=? AND event_type IN ('workflow-event','runtime-efficiency-event') AND COALESCE(json_extract(payload,'$.event.id'),json_extract(payload,'$.eventId'))=? LIMIT 1")
+                    .get(runId, durableId);
+                if (prior) {
+                    if (prior.payload !== encoded)
+                        throw new Error('A replayed Core event changed its committed content');
+                    return;
+                }
+            }
+            if (typeof event.type !== 'string')
+                throw new Error('Core event has no type');
+            if (event.type === 'runtime-efficiency-event' && event.kind === 'role-context' && object(event.payload) && object(event.payload.usage)) {
+                if (!durableId)
+                    throw new Error('Physical usage requires a durable event identity');
+                const p = event.payload, usage = p.usage;
+                const invocationId = text(p.invocationId), attemptId = text(event.attemptId), provider = text(p.provider);
+                const startedAt = timestamp(p.startedAt), finishedAt = timestamp(p.finishedAt);
+                if (!invocationId || !attemptId || !provider || !startedAt || !finishedAt || !['succeeded', 'failed', 'interrupted'].includes(String(p.status)))
+                    throw new Error('Incomplete physical invocation evidence');
+                const identity = `core:${runId}:${invocationId}`;
+                const priorEvidence = db.prepare("SELECT payload FROM events WHERE job_id=? AND event_type='runtime-efficiency-event' AND json_extract(payload,'$.payload.invocationId')=? LIMIT 1").get(runId, invocationId);
+                if (priorEvidence) {
+                    const original = JSON.parse(priorEvidence.payload);
+                    // Envelope sequence/time may differ on replay; physical identity,
+                    // attribution and the provider's reported usage must not diverge.
+                    const evidence = (value) => JSON.stringify(canonical([value.attemptId, value.nodePath, value.payload]));
+                    if (evidence(original) !== evidence(event))
+                        throw new Error('A physical Core invocation changed its committed evidence');
+                }
+                const targets = [...new Set(input.ticketIds)].sort((a, b) => a - b);
+                if (!targets.length)
+                    targets.push(null);
+                const prior = db.prepare('SELECT id FROM ai_invocations WHERE id=?').get(identity + (targets.length > 1 ? `:t${targets[0]}` : ''));
+                if (prior && !priorEvidence)
+                    throw new Error('Physical Core invocation is missing its committed evidence');
+                if (!prior) {
+                    const payload = { version: 1, runId, stepKey: identity, invocationId: identity, projectId: input.projectId, provider,
+                        model: text(p.model) ?? null, surfaceRefId: text(event.nodePath) ?? attemptId, ticketIds: input.ticketIds,
+                        startedAt, baseline: (0, loop_runs_store_1.readLoopJobUsage)(db, runId), completedEventSeq: -1, providerCostBaseline: 0, providerTurnsBaseline: 0, loopDurationBaseline: 0, completedDurationMs: number(p.durationMs) ?? 0 };
+                    (0, loop_runs_store_1.stageLoopStepRecovery)(db, payload);
+                    (0, loop_runs_store_1.setLoopStepSettledResult)(db, runId, identity, { provider, cost: number(usage.costUsd), tokensIn: number(usage.inputTokens), tokensOut: number(usage.outputTokens), durationMs: number(p.durationMs), failed: p.status !== 'succeeded' });
+                    (0, loop_runs_store_1.completeLoopStepRecovery)(db, runId, identity, () => {
+                        const inTokens = (0, distribute_int_1.distributeIntEvenly)(number(usage.inputTokens), targets.length), outTokens = (0, distribute_int_1.distributeIntEvenly)(number(usage.outputTokens), targets.length);
+                        const readTokens = (0, distribute_int_1.distributeIntEvenly)(number(usage.cacheReadInputTokens), targets.length), writeTokens = (0, distribute_int_1.distributeIntEvenly)(number(usage.cacheWriteInputTokens), targets.length);
+                        targets.forEach((ticketId, index) => (0, ai_invocations_1.recordInvocation)(db, { id: identity + (targets.length > 1 ? `:t${ticketId}` : ''), project_id: input.projectId, provider,
+                            model: text(p.model), surface: 'loop', surface_ref_id: `${attemptId}:${invocationId}`, loop_run_id: runId, ticket_id: ticketId,
+                            status: p.status === 'succeeded' ? 'success' : p.status === 'interrupted' ? 'aborted' : 'failed', started_at: startedAt, finished_at: finishedAt,
+                            total_cost_usd: number(usage.costUsd) === undefined ? undefined : Number(usage.costUsd) / targets.length, total_cost_usd_estimated: false,
+                            tokens_in: inTokens[index], tokens_out: outTokens[index], tokens_cache_read: readTokens[index], tokens_cache_create: writeTokens[index],
+                            duration_ms: number(p.durationMs) === undefined ? undefined : Number(p.durationMs) / targets.length,
+                        }));
+                    });
+                    nextTotals = readDefinitionUsage(db, runId);
+                }
+            }
+            if (nextTotals !== totals) {
+                db.prepare(`UPDATE jobs SET total_cost_usd=?,tokens_in=?,tokens_out=?,tokens_cache_read=?,tokens_cache_create=?,num_turns=? WHERE id=? AND owner='loop'`).run(nextTotals.present && !nextTotals.costUnknown ? nextTotals.cost : null, nextTotals.present && !nextTotals.tokensInUnknown ? nextTotals.tokensIn : null, nextTotals.present && !nextTotals.tokensOutUnknown ? nextTotals.tokensOut : null, nextTotals.present && !nextTotals.cacheReadUnknown ? nextTotals.cacheRead : null, nextTotals.present && !nextTotals.cacheCreateUnknown ? nextTotals.cacheCreate : null, nextTotals.present && !nextTotals.turnsUnknown ? nextTotals.turns : null, runId);
+                db.prepare('UPDATE loop_runs SET total_cost_usd=?,total_tokens=? WHERE id=?').run(nextTotals.cost, nextTotals.tokensIn + nextTotals.tokensOut, runId);
+            }
+            persist(event.type, event);
+            if (durableId)
+                db.prepare('UPDATE loop_runs SET core_event_cursor=MAX(COALESCE(core_event_cursor,0),?) WHERE id=? AND engine_version=2').run(workflow?.sequence ?? event.sequence, runId);
+            if (event.type === 'runtime-result')
+                (0, loop_runs_store_1.recordDefinitionCheckpoint)(db, runId, {
+                    ...(event.revision === undefined ? {} : { revision: event.revision }),
+                    ...(event.eventCursor === undefined ? {} : { eventCursor: event.eventCursor }),
+                    status: typeof event.status === 'string' ? event.status : undefined,
+                    pendingInterrupts: Array.isArray(event.pendingInterrupts) ? event.pendingInterrupts : [],
+                    ...(event.completion === undefined ? {} : { completion: event.completion }),
+                });
+            if (workflow && text(workflow.attemptId)) {
+                const attemptId = String(workflow.attemptId);
+                const prior = db.prepare("SELECT payload FROM events WHERE job_id=? AND event_type='loop_step' AND json_extract(payload,'$.attemptId')=? ORDER BY seq DESC LIMIT 1").get(runId, attemptId);
+                const opening = prior ? JSON.parse(prior.payload) : undefined;
+                const correlation = { nodeId: workflow.nodePath, nodePath: workflow.nodePath, scopeId: workflow.scopeId, branch: workflow.branch, visit: workflow.visit, attempt: workflow.attempt, attemptId, coreEventId: durableId, traceId: workflow.traceId, spanId: workflow.spanId };
+                if (workflow.type === 'step_started' && !opening) {
+                    nextCount += 1;
+                    persist('loop_step', { index: nextCount, kind: 'core', title: workflow.nodePath, iteration: workflow.visit, startedAtMs: Date.parse(at), ...correlation });
+                }
+                else if (opening && ['step_succeeded', 'step_failed', 'step_blocked', 'step_interrupted', 'step_retrying', 'step_paused'].includes(String(workflow.type))) {
+                    persist('loop_step_end', { index: opening.index, status: workflow.type === 'step_succeeded' ? 'ok' : workflow.type === 'step_paused' ? 'paused' : workflow.type === 'step_interrupted' ? 'interrupted' : 'failed',
+                        runtimeStatus: String(workflow.type).slice(5), outcome: workflow.outcome, exitCode: null,
+                        durationMs: Math.max(0, Date.parse(at) - Number(opening.startedAtMs)), ...correlation });
+                }
+            }
+        })();
+        count = nextCount;
+        totals = nextTotals;
+        for (const projected of outgoing)
+            input.broadcast(projected);
+        if (outgoing.length)
+            input.onProgress?.(count, totals);
+    };
+}

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

@@ -0,0 +1,106 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeDefinitionRun = probeDefinitionRun;
+exports.probeDefinitionRuns = probeDefinitionRuns;
+exports.toDefinitionStates = toDefinitionStates;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const core_node_runtime_1 = require("../../../core-node-runtime");
+const win_spawn_1 = require("../../../util/win-spawn");
+const agent_runtime_bridge_1 = require("../../agent-runtime/runtime/agent-runtime-bridge");
+const agent_runtime_package_1 = require("../../agent-runtime/runtime/agent-runtime-package");
+const loop_runs_store_1 = require("./loop-runs-store");
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Read only through the retained CLI. Failed inspection preserves ownership for a later explicit decision. */
+async function probeDefinitionRun(ctx, runId, includeOutputs = false) {
+    const unavailable = (message) => ({ runId, engineVersion: 2, status: 'unavailable', resumable: false,
+        lease: null, recoverableSteps: [], pendingInterrupts: [], completion: null, coreRevision: null, eventCursor: null,
+        probedAt: new Date().toISOString(), error: { code: 'runtime_status_unavailable', message: message.slice(0, 2000) } });
+    try {
+        const frozen = (0, loop_runs_store_1.readDefinitionRun)(ctx.db, runId), contextPath = frozen?.metadata.contextPath;
+        if (!frozen || !contextPath || !node_path_1.default.isAbsolute(contextPath))
+            return unavailable('Frozen Core context is unavailable');
+        const context = JSON.parse((0, node_fs_1.readFileSync)(contextPath, 'utf8'));
+        if (context.runId !== runId || typeof context.backlogRoot !== 'string' || (0, node_fs_1.realpathSync)(contextPath) !== node_path_1.default.join((0, node_fs_1.realpathSync)(context.backlogRoot), '.specrails', 'pipeline', runId, 'desktop-context.json'))
+            return unavailable('Frozen Core context belongs to another run or path');
+        let host;
+        let scopeError;
+        let selector = ['--context', contextPath];
+        try {
+            host = (0, agent_runtime_bridge_1.readFrozenRuntimeHost)(contextPath, ctx.env, runId);
+        }
+        catch (error) {
+            // Released mounts cannot authorize execution, but the owned retained
+            // ledger can still answer a read-only status request. Never substitute
+            // today's project checkout for the frozen execution scope.
+            const runDirectory = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'agent-workflow');
+            if ((0, node_fs_1.realpathSync)(runDirectory) !== runDirectory || (0, node_fs_1.realpathSync)(node_path_1.default.join(runDirectory, 'run.sqlite')) !== node_path_1.default.join(runDirectory, 'run.sqlite'))
+                return unavailable('Retained run ledger is outside its original directory');
+            scopeError = error instanceof Error ? error.message : 'Original workflow scope is unavailable';
+            host = { cwd: node_path_1.default.dirname(contextPath), env: { ...ctx.env, SPECRAILS_GIT_AUTO: 'false' } };
+            selector = ['--run-dir', runDirectory];
+        }
+        const cli = (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(contextPath);
+        const { stdout } = await (0, node_util_1.promisify)(node_child_process_1.execFile)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [cli, 'status', ...selector, ...(includeOutputs ? [] : ['--compact'])], {
+            cwd: host.cwd, env: (0, win_spawn_1.windowsSpawnEnv)(host.env), windowsHide: true, timeout: 15_000, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8',
+        });
+        const result = JSON.parse(stdout);
+        if (!record(result) || result.type !== 'runtime-status' || result.engineVersion !== 2 || !record(result.state))
+            return unavailable('Retained Core returned an incompatible status');
+        const state = result.state;
+        if (state.runId !== runId || !['paused', 'running', 'succeeded', 'failed', 'blocked', 'cancelled'].includes(String(state.status)) || !integer(result.revision) || !integer(result.eventCursor))
+            return unavailable('Retained Core returned an invalid run identity or cursor');
+        const lease = state.lease;
+        if (lease !== null && (!record(lease) || typeof lease.owner !== 'string' || !integer(lease.epoch) || !integer(lease.expiresAt) || typeof lease.active !== 'boolean'))
+            return unavailable('Retained Core returned an invalid lease');
+        if (!Array.isArray(state.recoverableSteps) || state.recoverableSteps.length > 10_000 || state.recoverableSteps.some(value => !record(value) || typeof value.attemptId !== 'string' || !value.attemptId || typeof value.nodePath !== 'string' || typeof value.scopeId !== 'string'))
+            return unavailable('Retained Core returned invalid recovery attempts');
+        if (!Array.isArray(state.pendingInterrupts) || state.pendingInterrupts.length > 10_000 || state.pendingInterrupts.some(value => !record(value) || typeof value.id !== 'string' || typeof value.nodePath !== 'string' || !['question', 'approval', 'gate'].includes(String(value.kind))))
+            return unavailable('Retained Core returned invalid interrupts');
+        if (includeOutputs && (!Array.isArray(state.scopes) || state.scopes.length > 10_000 || state.scopes.some(value => !record(value) || typeof value.nodePath !== 'string' || typeof value.scopeId !== 'string' || typeof value.kind !== 'string' || typeof value.status !== 'string' || (value.attemptId !== null && typeof value.attemptId !== 'string'))))
+            return unavailable('Retained Core returned invalid scoped evidence');
+        const completion = result.completion;
+        if (completion !== null && (!record(completion) || typeof completion.ok !== 'boolean' || typeof completion.verified !== 'boolean' || !Array.isArray(completion.reasons) || completion.reasons.some(reason => typeof reason !== 'string')))
+            return unavailable('Retained Core returned invalid completion evidence');
+        return { runId, engineVersion: 2, status: state.status, lease: lease,
+            resumable: !scopeError && !lease?.active && completion === null && !['succeeded', 'cancelled'].includes(String(state.status)),
+            recoverableSteps: state.recoverableSteps.map(value => ({ attemptId: value.attemptId, nodePath: value.nodePath, scopeId: value.scopeId })),
+            pendingInterrupts: state.pendingInterrupts, completion: completion,
+            ...(includeOutputs ? { scopes: state.scopes } : {}),
+            coreRevision: result.revision, eventCursor: result.eventCursor, probedAt: new Date().toISOString(),
+            ...(scopeError ? { error: { code: 'runtime_scope_unavailable', message: scopeError.slice(0, 2000) } } : {}) };
+    }
+    catch (error) {
+        return unavailable(error instanceof Error ? error.message : 'Retained runtime inspection failed');
+    }
+}
+/** Bound subprocess fan-out independently of the number of historical runs. */
+async function probeDefinitionRuns(ctx, runIds, includeOutputs = false) {
+    const results = new Map(), ids = [...new Set(runIds)];
+    let cursor = 0;
+    await Promise.all(Array.from({ length: Math.min(4, ids.length) }, async () => {
+        for (;;) {
+            const id = ids[cursor++];
+            if (id === undefined)
+                return;
+            results.set(id, await probeDefinitionRun(ctx, id, includeOutputs));
+        }
+    }));
+    return results;
+}
+function toDefinitionStates(probes) {
+    return new Map([...probes].map(([id, probe]) => [id, {
+            // Preserve even unavailable/terminal Core rows until Desktop explicitly
+            // settles their original delivery. A failed probe is not failed work.
+            status: probe.status === 'paused' ? 'paused' : 'interrupted', coreStatus: probe.status,
+            ...(probe.coreRevision === null ? {} : { revision: probe.coreRevision }), ...(probe.eventCursor === null ? {} : { eventCursor: probe.eventCursor }),
+            lease: probe.lease, completion: probe.completion, pendingInterrupts: probe.pendingInterrupts, recoverableSteps: probe.recoverableSteps,
+            ...(probe.error ? { error: probe.error } : {}),
+        }]));
+}

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDefinitionLoop = runDefinitionLoop;
+/** One retained Core process at a time; all graph scheduling remains in Core. */
+async function runDefinitionLoop(request, runId, ports) {
+    let continuation = ports.continuation ?? {};
+    for (;;) {
+        if (ports.isCancelled())
+            return { text: '', runtimeStatus: 'cancelled', failed: true };
+        const result = await ports.invoke({ request, runId, contextPath: ports.contextPath?.(), ...continuation,
+            onPrepared: ports.onPrepared, onLine: ports.onLine, onRuntimeEvent: ports.onRuntimeEvent, onSpawn: ports.onSpawn, timeoutMs: ports.remainingMs() });
+        ports.onInvocationEnd(result);
+        if (ports.isCancelled())
+            return { ...result, runtimeStatus: 'cancelled', failed: true };
+        if (result.runtimeStatus !== 'paused')
+            return result;
+        const pending = result.pendingInterrupts ?? [];
+        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}`;
+        }).join('\n');
+        if (!pending.length)
+            throw new Error('Core paused without an addressable interrupt');
+        const decision = await ports.awaitHumanDecision(reason, pending);
+        if (decision.action === 'stop' || ports.isCancelled())
+            return { ...result, runtimeStatus: 'cancelled', failed: true };
+        const selected = decision.interruptId ? pending.find(item => item.id === decision.interruptId) : pending.length === 1 ? pending[0] : undefined;
+        if (!selected)
+            throw new Error('Select the pending question or approval to resume');
+        if (selected.kind !== 'question' && decision.approve !== true)
+            throw new Error('Explicit approval is required to resume this interrupt');
+        continuation = selected.kind === 'question'
+            ? { resume: true, answer: decision.text, interruptId: selected.id }
+            : { resume: true, approve: [selected.id], interruptId: selected.id };
+    }
+}