specrails-desktop 2.55.0 → 2.56.0

package/server/dist/{revision-seed.js → modules/execution/runtime/revision-seed.js}

@@ -40,7 +40,7 @@ function buildRevisionSeed(input) {
     const specs = (input.specSnapshot ?? []).length > 0
         ? (input.specSnapshot ?? []).map((entry) => [
             `### #${entry.ticketId} ${entry.title ?? '(untitled)'}`,
-            entry.description ? clamp(entry.description, exports.SEED_SPEC_BODY_CAP) : '(no description recorded)',
+            ...(input.includeSpecBody === false ? [] : [entry.description ? clamp(entry.description, exports.SEED_SPEC_BODY_CAP) : '(no description recorded)']),
         ].join('\n')).join('\n\n')
         : input.ticketIds.map((id) => `### #${id}\n(spec text was not captured at launch)`).join('\n\n');
     return [

package/server/dist/{spawn-lifecycle.js → modules/execution/runtime/spawn-lifecycle.js}

@@ -14,9 +14,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAiCliInvocation = runAiCliInvocation;
 const node_readline_1 = require("node:readline");
-const win_spawn_1 = require("./util/win-spawn");
-const cli_prompt_1 = require("./util/cli-prompt");
-const runtime_1 = require("./providers/runtime");
+const win_spawn_1 = require("../../../util/win-spawn");
+const cli_prompt_1 = require("../../../util/cli-prompt");
+const runtime_1 = require("../../../providers/runtime");
 const STDERR_TAIL_CAP = 64 * 1024;
 /**
  * Run one AI-CLI invocation: spawn → stream → settle. Resolves exactly once on

package/server/dist/{stuck-run-detector.js → modules/execution/runtime/stuck-run-detector.js}

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StuckRunDetector = exports.STUCK_SWEEP_INTERVAL_MS = exports.STUCK_FLOOR_MS = void 0;
 exports.resolveStuckThresholdMs = resolveStuckThresholdMs;
 exports.findStuckCandidates = findStuckCandidates;
-const loop_runs_store_1 = require("./loop-runs-store");
+const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
 /** Never notify sooner than this, however the threshold is configured. */
 exports.STUCK_FLOOR_MS = 10 * 60 * 1000;
 /** How often the sweep runs while the server is up. */

package/server/dist/{loop-command-catalog.js → modules/loops/runtime/loop-command-catalog.js}

@@ -26,7 +26,7 @@ exports.expandCommands = expandCommands;
 exports.dominantTicketScope = dominantTicketScope;
 exports.referencesClaudeOnlyCommand = referencesClaudeOnlyCommand;
 exports.referencesUnsupportedProviderCommand = referencesUnsupportedProviderCommand;
-const registry_1 = require("./providers/registry");
+const registry_1 = require("../../../providers/registry");
 const loop_constants_1 = require("./loop-constants");
 /** The autonomous prompt a `native` command (Freestyle) expands to for the
  *  LoopRunManager path. Factory Freestyle loops route to QueueManager's real

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

@@ -9,30 +9,30 @@ exports.createLoopExecutors = createLoopExecutors;
  * from coverage; the engine's traversal/decision logic is unit-tested against
  * fake executors in `loop-run-manager.test.ts`.
  */
-const core_completion_1 = require("./core-completion");
-const core_execution_1 = require("./core-execution");
-const agent_runtime_bridge_1 = require("./agent-runtime-bridge");
-const codex_spawn_1 = require("./plugins/codex-spawn");
+const core_completion_1 = require("../../../core-completion");
+const core_execution_1 = require("../../../core-execution");
+const agent_runtime_bridge_1 = require("../../agent-runtime/runtime/agent-runtime-bridge");
+const codex_spawn_1 = require("../../../plugins/codex-spawn");
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 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 workspace_manager_1 = require("./workspace-manager");
-const claude_trust_1 = require("./claude-trust");
-const spawn_lifecycle_1 = require("./spawn-lifecycle");
-const result_event_1 = require("./result-event");
-const terminal_result_1 = require("./providers/terminal-result");
-const claude_background_tasks_1 = require("./providers/claude-background-tasks");
+const win_spawn_1 = require("../../../util/win-spawn");
+const providers_1 = require("../../../providers");
+const registry_1 = 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");
+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_decider_1 = require("./loop-decider");
-const rail_isolation_1 = require("./rail-isolation");
-const repo_map_1 = require("./repo-map");
-const feature_flags_1 = require("./feature-flags");
+const rail_isolation_1 = require("../../delivery/runtime/rail-isolation");
+const repo_map_1 = require("../../../repo-map");
+const feature_flags_1 = require("../../../feature-flags");
 const loop_step_idle_1 = require("./loop-step-idle");
-const runtime_1 = require("./providers/runtime");
+const runtime_1 = require("../../../providers/runtime");
 const loop_shell_invocation_1 = require("./loop-shell-invocation");
 // Per-step wall-clock caps so a single hung step can't block the engine's
 // overall deadline check (which only runs between nodes).

package/server/dist/{loop-factory.js → modules/loops/runtime/loop-factory.js}

@@ -42,7 +42,7 @@ const SDD_QUICK_OPENSPEC_FACTORY = {
     mode: 'loop',
     graph: (0, loop_templates_1.opsxLifecycleGraph)(),
 };
-/** The Architect-less revision loop every "ask for a change" launch runs. */
+/** Legacy persisted id. Resolves to Quick SDD; no Revision loop is listed or run. */
 exports.FACTORY_REVISION_LOOP_ID = 'factory:revision';
 exports.FACTORY_LOOPS = [
     {
@@ -70,30 +70,11 @@ exports.FACTORY_LOOPS = [
         requiredCapability: 'freestyle',
         graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:freestyle}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN),
     },
-    {
-        id: exports.FACTORY_REVISION_LOOP_ID,
-        name: 'Revision',
-        // Listed so the platform's behaviour is discoverable, but `launchable:false`:
-        // the app runs this itself when a user asks for a change to a delivery. Its
-        // prompt consumes `{{const:REVISION_REQUEST}}`, and an unresolved constant
-        // renders as an EMPTY string, so a hand-launched run would have a blank
-        // central instruction. The launch route refuses it; the prompt guards too.
-        launchable: false,
-        description: "Apply the ONE change the user asked for on top of work already delivered, then run one independent reviewer-owned verification gate and refine until green. No re-planning. Runs automatically when you ask for changes on a review — it is not started by hand.",
-        mode: 'loop',
-        // Revision is the ONLY factory loop that swaps the generic `{{cmd:verify}}`
-        // gate: `{{cmd:revision-verify}}` owns reviewer re-grading AND the full pass
-        // of record in ONE read-only step, so the mutator no longer runs sr-reviewer
-        // itself and no second repository-wide gate follows it. The trailing `true`
-        // makes verify/fix run in a FRESH provider session — the gate's verdict and
-        // its confidence artifact then describe the candidate on disk rather than
-        // the mutator's own account of it.
-        graph: (0, loop_templates_1.fixLoopGraph)(['{{cmd:revise}}'], GREEN_GOAL, FACTORY_MAX_ITERATIONS, FACTORY_LOOP_TIMEOUT_MIN, FACTORY_AI_STEP_TIMEOUT_MIN, '{{cmd:revision-verify}}', true),
-    },
     SDD_QUICK_OPENSPEC_FACTORY,
 ];
 const FACTORY_ALIASES = new Map([
     ['factory:openspec', SDD_QUICK_OPENSPEC_FACTORY],
+    [exports.FACTORY_REVISION_LOOP_ID, SDD_QUICK_OPENSPEC_FACTORY],
 ]);
 const FACTORY_BY_ID = new Map([
     ...exports.FACTORY_LOOPS.map((f) => [f.id, f]),

package/server/dist/{loop-graph.js → modules/loops/runtime/loop-graph.js}

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertLoopShellRepositoryScope = assertLoopShellRepositoryScope;
+exports.assertLoopFailureRecovery = assertLoopFailureRecovery;
 exports.emptyLoopGraph = emptyLoopGraph;
 exports.validateLoopGraph = validateLoopGraph;
 exports.nodesById = nodesById;
@@ -27,6 +28,24 @@ function assertLoopShellRepositoryScope(graph, repositoryIds) {
         }
     }
 }
+/** Recovery is bounded and may only repeat a phase or repair artifacts before revalidation. */
+function assertLoopFailureRecovery(graph) {
+    for (const node of graph.nodes) {
+        const recovery = node.data?.failureRecovery;
+        if (recovery === undefined)
+            continue;
+        const target = graph.nodes.find((candidate) => candidate.id === recovery?.target);
+        if (!recovery || node.data?.stopOnFailure !== true ||
+            !['ai-step', 'shell'].includes(node.type) ||
+            recovery.maxRetries !== 1 ||
+            (recovery.artifactOnly !== undefined && typeof recovery.artifactOnly !== 'boolean') ||
+            !target || (target.id !== node.id &&
+            !(node.type === 'shell' && target.type === 'ai-step' && recovery.artifactOnly === true)) ||
+            (recovery.artifactOnly === true && (target?.type !== 'ai-step' || target.data?.operation === 'core-implementation' || target.data?.stopOnFailure !== true))) {
+            throw new Error(`Invalid failure recovery for step ${node.id}: use one retry of this phase or an AI artifact repair.`);
+        }
+    }
+}
 /** A minimal, structurally-valid empty graph (used to seed a new Draft). */
 function emptyLoopGraph() {
     return { nodes: [], edges: [], config: { maxIterations: 10, timeoutMinutes: 30 } };
@@ -70,6 +89,12 @@ function validateLoopGraph(graph) {
             errors.push({ code: 'INVALID_NODE', nodeId: node.id, message: 'A shell repositoryId must be a non-empty registered repository id.' });
         }
     }
+    try {
+        assertLoopFailureRecovery(graph);
+    }
+    catch (error) {
+        errors.push({ code: 'INVALID_NODE', message: error.message });
+    }
     // ── Start cardinality ──────────────────────────────────────────────────────
     const starts = nodes.filter((n) => n.type === 'start');
     if (starts.length === 0) {

package/server/dist/{loop-role-engines.js → modules/loops/runtime/loop-role-engines.js}

@@ -29,10 +29,10 @@ exports.resolveLoopRoleEngine = resolveLoopRoleEngine;
 // `agent-runtime.json`; absent ⇒ every loop role inherits the project's primary.
 const node_fs_1 = require("node:fs");
 const node_path_1 = __importDefault(require("node:path"));
-const providers_1 = require("./providers");
-const spec_models_1 = require("./spec-models");
-const workspace_resolution_1 = require("./workspace-resolution");
-const provider_selection_1 = require("./provider-selection");
+const providers_1 = require("../../../providers");
+const spec_models_1 = require("../../specs/runtime/spec-models");
+const workspace_resolution_1 = require("../../../workspace-resolution");
+const provider_selection_1 = require("../../../provider-selection");
 /** The rail engine value meaning "per-role engines, no flattening override". */
 exports.ROLES_ENGINE = 'roles';
 exports.LOOP_ROLES = ['verifier', 'decider'];

package/server/dist/{loop-run-manager.js → modules/loops/runtime/loop-run-manager.js}

@@ -10,29 +10,31 @@ exports.seedChangeId = seedChangeId;
 exports.openspecChangeState = openspecChangeState;
 exports.extractChangeId = extractChangeId;
 exports.recoverOrphanLoopStepAccounting = recoverOrphanLoopStepAccounting;
+const crypto_1 = require("crypto");
+const spec_addenda_core_1 = require("../../specs/runtime/spec-addenda-core");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
-const agent_runtime_events_1 = require("./agent-runtime-events");
-const agent_runtime_settings_1 = require("./agent-runtime-settings");
-const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
-const win_spawn_1 = require("./util/win-spawn");
-const db_1 = require("./db");
-const interactive_job_session_1 = require("./interactive-job-session");
+const agent_runtime_events_1 = require("../../agent-runtime/runtime/agent-runtime-events");
+const agent_runtime_settings_1 = require("../../agent-runtime/runtime/agent-runtime-settings");
+const multi_repo_execution_store_1 = require("../../delivery/runtime/multi-repo-execution-store");
+const win_spawn_1 = require("../../../util/win-spawn");
+const db_1 = require("../../../db");
+const interactive_job_session_1 = require("../../execution/runtime/interactive-job-session");
 const loop_graph_1 = require("./loop-graph");
 const loop_command_catalog_1 = require("./loop-command-catalog");
 const loop_constants_1 = require("./loop-constants");
 const loop_step_idle_1 = require("./loop-step-idle");
 const loop_decider_1 = require("./loop-decider");
 const loop_runs_store_1 = require("./loop-runs-store");
-const ai_invocations_1 = require("./ai-invocations");
-const provider_limit_1 = require("./provider-limit");
-const ids_1 = require("./ids");
-const providers_1 = require("./providers");
-const agent_runtime_accounting_1 = require("./agent-runtime-accounting");
-const runtime_1 = require("./providers/runtime");
-const result_event_1 = require("./result-event");
-const rails_store_1 = require("./rails-store");
-const verification_sentinel_1 = require("./verification-sentinel");
+const ai_invocations_1 = require("../../accounting/runtime/ai-invocations");
+const provider_limit_1 = require("../../../provider-limit");
+const ids_1 = require("../../../ids");
+const providers_1 = require("../../../providers");
+const agent_runtime_accounting_1 = require("../../agent-runtime/runtime/agent-runtime-accounting");
+const runtime_1 = require("../../../providers/runtime");
+const result_event_1 = require("../../accounting/runtime/result-event");
+const rails_store_1 = require("../../delivery/runtime/rails-store");
+const verification_sentinel_1 = require("../../execution/runtime/verification-sentinel");
 const IMPLEMENT_CMD_TOKEN_RE = /\{\{\s*cmd:(?:implement|batch)\s*\}\}/;
 const IMPLEMENT_CMD_TEXT_RE = /(?:^|\s)(?:\/(?:specrails:|sr:)?(?:implement|batch-implement)|\$(?:implement|batch-implement))\b/;
 const LOOP_BLOCKED_LINE_RE = /(?:^|\n)\s*LOOP_BLOCKED:\s*(.+?)(?:\n|$)/i;
@@ -141,9 +143,20 @@ function resolveRunVars(text, vars) {
     return text.replace(RUN_TOKEN_RE, (_m, key) => vars[key] ?? '');
 }
 const CHANGE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,99}$/i;
-/** The durable OpenSpec change name a launch already carries, if any: the
- *  follow-up's declared name wins, else the spec's `openspecChangeName`. */
+/** The authoritative OpenSpec target for a launch.
+ *  Addenda/delivery deltas get a run-specific name; ordinary launches use the
+ *  follow-up's declared name, else the spec's `openspecChangeName`. */
 function seedChangeId(req) {
+    if (req.addenda?.ids.length) {
+        // A new generation never picks an old/archived proposal, even when the
+        // ticket metadata still names it. Resuming the same run keeps its target.
+        const hash = (0, crypto_1.createHash)('sha256').update(JSON.stringify([req.runId, req.addenda.ids, req.addenda.briefing])).digest('hex').slice(0, 20);
+        return { id: `spec-addenda-${hash}`, source: 'addenda' };
+    }
+    if (req.constants?.REVISION_REQUEST) {
+        const hash = (0, crypto_1.createHash)('sha256').update(JSON.stringify([req.runId, req.constants.REVISION_REQUEST])).digest('hex').slice(0, 20);
+        return { id: `delivery-change-${hash}`, source: 'revision' };
+    }
     const fromFollowUp = typeof req.followUp?.openspecChangeName === 'string' ? req.followUp.openspecChangeName.trim() : '';
     if (fromFollowUp && CHANGE_NAME_RE.test(fromFollowUp))
         return { id: fromFollowUp, source: 'followUp' };
@@ -605,6 +618,13 @@ class LoopRunManager {
         // Later fresh steps must verify the admitted spec, even if its caller or
         // backlog changes while the implementation is running.
         req = { ...req, runtimeProviderOverride: (0, agent_runtime_settings_1.validateRuntimeProviderOverride)(req.runtimeProviderOverride), graph: structuredClone(req.graph) };
+        (0, loop_graph_1.assertLoopFailureRecovery)(req.graph);
+        if (req.addenda)
+            req = { ...req, addenda: structuredClone(req.addenda) };
+        if (req.followUp)
+            req = { ...req, followUp: structuredClone(req.followUp) };
+        if (req.constants)
+            req = { ...req, constants: structuredClone(req.constants) };
         if (req.spec)
             req = { ...req, spec: structuredClone(req.spec) };
         if (req.executionManifest)
@@ -902,7 +922,7 @@ class LoopRunManager {
         // change in one go (run 644eb404) never mentioned an active path, so the
         // validate/archive shell steps refused to run and a green implementation
         // settled `failed`. A step's own capture still wins when nothing is seeded.
-        const seededChangeId = seedChangeId(req);
+        const seededChangeId = seedChangeId({ ...req, runId });
         if (seededChangeId) {
             runVars.changeId = seededChangeId.id;
             logLine(`↪ OpenSpec change id seeded from ${seededChangeId.source}: ${seededChangeId.id}`);
@@ -1087,6 +1107,27 @@ class LoopRunManager {
             });
             return decision;
         };
+        const recoveryCounts = new Map();
+        let phaseRecovery;
+        const recoverPhase = (node, detail, previousFailure) => {
+            const policy = node.data?.failureRecovery;
+            if (!policy || phaseRecovery || this._cancelled.has(runId) ||
+                (recoveryCounts.get(node.id) ?? 0) >= policy.maxRetries)
+                return undefined;
+            recoveryCounts.set(node.id, (recoveryCounts.get(node.id) ?? 0) + 1);
+            phaseRecovery = { failedId: node.id, target: policy.target, detail: truncate(detail, 4000), artifactOnly: policy.artifactOnly === true };
+            passFailed = previousFailure;
+            emitRunEvent('loop_phase_recovery', { nodeId: node.id, target: policy.target, attempt: recoveryCounts.get(node.id) });
+            logLine(`↪ Recovering phase ${node.id} once; preserving completed phases and the current change.`);
+            return policy.target;
+        };
+        const afterPhase = (nodeId, successor) => {
+            if (phaseRecovery?.target !== nodeId)
+                return successor;
+            const failedId = phaseRecovery.failedId;
+            phaseRecovery = undefined;
+            return failedId === nodeId ? successor : failedId;
+        };
         const firstStepId = start ? req.graph.edges.find((e) => e.source === start.id)?.target : undefined;
         try {
             let nodeId = start?.id;
@@ -1144,16 +1185,24 @@ class LoopRunManager {
                         // NATIVE per-provider invocation (claude `/specrails:implement #<id>
                         // --yes`, codex `$implement #<id> --yes`) — then resolve `{{spec.*}}`
                         // data tokens and finally `{{const:*}}` library constants.
-                        const rawTemplate = String(node.data?.prompt ?? '');
+                        const priorPhaseFailure = passFailed;
+                        const repair = phaseRecovery?.target === node.id ? phaseRecovery : undefined;
+                        const rawTemplate = repair?.artifactOnly
+                            ? 'Repair ONLY the OpenSpec artifacts at openspec/changes/{{run.changeId}}/ using the validation diagnostics below. 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 requiresCoreCompletion = node.data?.operation === 'core-implementation' || /\{\{\s*cmd:(?:implement|batch)\s*\}\}/.test(rawTemplate)
                             || /^\s*(?:\/specrails:|\/skill:specrails-|\$)(?:implement|batch-implement)(?:\s|$)/.test(rawTemplate);
-                        const expanded = (0, loop_constants_1.resolveConstants)(resolveRunVars((0, loop_graph_1.interpolateSpec)((0, loop_command_catalog_1.expandCommands)(rawTemplate, { provider: nodeProvider, ticketIds: req.spec?.ticketIds, specId: req.spec?.id }), req.spec), runVars), constMap);
+                        const expanded = (0, loop_constants_1.resolveConstants)(resolveRunVars((0, loop_graph_1.interpolateSpec)((0, loop_command_catalog_1.expandCommands)(rawTemplate, { provider: nodeProvider, ticketIds: req.spec?.ticketIds, specId: req.spec?.id }), seededChangeId && ['addenda', 'revision'].includes(seededChangeId.source)
+                            ? { ...req.spec, openspecChangeName: seededChangeId.id } : req.spec), runVars), constMap);
                         // The follow-up briefing is APPENDED (after any slash command, which
                         // must lead the message) so it becomes part of the command's
                         // arguments for CLI providers and plain prompt text for the runner.
                         // The spec-addenda briefing rides the same slot: appended to every
                         // step so no phase can miss the iteration delta.
-                        const base = [(0, multi_repo_execution_store_1.executionManifestPrompt)(req.executionManifest), withReviewContinuationContext(expanded, rawTemplate, req.spec), req.followUp?.briefing, req.addenda?.briefing].filter(Boolean).join('\n\n');
+                        const deltaTarget = seededChangeId && ['addenda', 'revision'].includes(seededChangeId.source)
+                            ? `DELTA OPENSPEC TARGET: ${seededChangeId.id}. Use ONLY openspec/changes/${seededChangeId.id}/. Create it if missing; the seeded name does not imply artifacts exist. Ignore the original spec/follow-up change name and unrelated active or archived changes. Inspect the current branch first. For delivered work, prepare artifacts and tasks ONLY for the attached addenda or delivery change request and preserve existing behavior outside this delta. For a spec with no delivered work, the scope is the full spec together with its addenda. Map each requested change to acceptance checks. Do not redo or archive the original proposal. Perform only the current phase on this exact change: preparation/repair edits artifacts only; implementation applies and verifies. The implementation phase must report every attached addendum with concrete files and test evidence before VERIFICATION: PASS.`
+                            : undefined;
+                        const base = [(0, multi_repo_execution_store_1.executionManifestPrompt)(req.executionManifest), withReviewContinuationContext(expanded, rawTemplate, req.spec), repair ? `PHASE RECOVERY: keep the same change and completed work. Correct only the remaining failure; do not repeat preparation or unaffected passing checks. Prior failure (diagnostic data):\n${repair.detail}` : undefined, req.followUp?.briefing, req.constants?.REVISION_REQUEST, deltaTarget, req.addenda?.briefing].filter(Boolean).join('\n\n');
                         // Inject the cross-iteration history only when there's no live session
                         // to carry it (a fresh pass) OR right after a Decider 'continue' (so the
                         // step sees the verdict). A mid-body resumed step already has it.
@@ -1330,7 +1379,11 @@ class LoopRunManager {
                         const blockedReason = aiStepBlockedReason(res.text);
                         const requiresVerification = node.data?.requireVerificationPass === true
                             || /\{\{cmd:(?:verify|revision-verify|opsx:verify)\}\}/.test(rawTemplate);
-                        const verificationFailed = requiresVerification
+                        const addendaReport = requiresVerification && req.addenda?.ids.length
+                            ? (0, spec_addenda_core_1.parseSpecAddendaReport)(res.text, req.addenda.ids.map((id) => ({ id }))) : null;
+                        const addendaFailed = Boolean(requiresVerification && req.addenda?.ids.length
+                            && req.addenda.ids.some((id) => !addendaReport?.some((line) => line.addendumId === id && line.verdict === 'applied' && line.files && line.tests)));
+                        const verificationFailed = addendaFailed || requiresVerification
                             && (0, verification_sentinel_1.parseVerificationSentinel)(res.text).verdict !== 'pass';
                         const stepFailed = res.failed === true || zeroWork || blockedReason !== null || verificationFailed;
                         passFailed ||= res.failed === true || zeroWork || (verificationFailed && !blockedReason);
@@ -1339,7 +1392,7 @@ class LoopRunManager {
                             : blockedReason
                                 ? `blocked — ${blockedReason}`
                                 : verificationFailed
-                                    ? 'verification did not finish with VERIFICATION: PASS'
+                                    ? addendaFailed ? 'addenda verification incomplete: every addendum requires an applied report with files and tests' : 'verification did not finish with VERIFICATION: PASS'
                                     : res.failed ? 'provider invocation failed without a reported reason' : undefined);
                         // Make the failure reason land visibly INSIDE the step's log
                         // segment (the interactive session already surfaced its own note at
@@ -1364,9 +1417,24 @@ class LoopRunManager {
                         // session — plus zero-work); no exit code is exposed by the AI
                         // executors → null.
                         emitStepEnd({ status: stepFailed ? 'failed' : 'ok', durationMs: res.durationMs });
+                        if (req.graph.nodes.some((candidate) => candidate.data?.failureRecovery)) {
+                            emitRunEvent('loop_phase_metrics', {
+                                nodeId: node.id, stepIndex: stepNum, usageScope: 'final-attempt', recovery: !!repair, promptChars: prompt.length, outputChars: res.text.length,
+                                durationMs: res.durationMs ?? null, costUsd: res.cost ?? null, estimated: res.estimated ?? null,
+                                tokensIn: res.tokensIn ?? null, tokensOut: res.tokensOut ?? null,
+                                tokensCacheRead: res.tokensCacheRead ?? null, tokensCacheCreate: res.tokensCacheCreate ?? null,
+                            });
+                        }
                         // Linear workflows may forbid later actions (such as archive) after
                         // a failed step. Verify/fix loops keep their existing recovery path.
                         if (node.data?.stopOnFailure === true && stepFailed) {
+                            const retryTarget = !res.failed && !res.resultIsError && !zeroWork && !blockedReason && verificationFailed
+                                ? recoverPhase(node, `${stepErrorText}\n${res.text}`, priorPhaseFailure) : undefined;
+                            if (retryTarget) {
+                                aiSessionId = res.sessionId;
+                                nodeId = retryTarget;
+                                break;
+                            }
                             outcome = 'failed';
                             settled = true;
                             break;
@@ -1426,10 +1494,11 @@ class LoopRunManager {
                         else {
                             consecutiveAiFailures = 0;
                         }
-                        nodeId = succs[0]?.id;
+                        nodeId = afterPhase(node.id, succs[0]?.id);
                         break;
                     }
                     case 'shell': {
+                        const priorPhaseFailure = passFailed;
                         // Guard: refuse to run when a declared run-variable was never captured
                         // (e.g. an archive node whose `{{run.changeId}}` is empty) — running
                         // `openspec archive  -y` against an unknown change would archive the
@@ -1461,7 +1530,7 @@ class LoopRunManager {
                             && openspecChangeState(shellCwd, runVars.changeId) === 'archived') {
                             logLine(`Skipped: OpenSpec change ${runVars.changeId} is already archived (openspec/changes/archive) — nothing left to ${/\barchive\b/.test(rawCommand) ? 'archive' : 'validate'}.`);
                             emitStepEnd({ status: 'ok', exitCode: 0, durationMs: 0 });
-                            nodeId = succs[0]?.id;
+                            nodeId = afterPhase(node.id, succs[0]?.id);
                             break;
                         }
                         logLine(`$ ${command}`);
@@ -1481,11 +1550,17 @@ class LoopRunManager {
                         });
                         history.push(`Shell \`${command}\` exit=${sh.exitCode}: ${truncate(sh.stdout || sh.stderr)}`);
                         if (node.data?.stopOnFailure === true && sh.exitCode !== 0) {
+                            const retryTarget = sh.exitCode === 1
+                                ? recoverPhase(node, `${command}\n${sh.stdout}\n${sh.stderr}`, priorPhaseFailure) : undefined;
+                            if (retryTarget) {
+                                nodeId = retryTarget;
+                                break;
+                            }
                             outcome = 'failed';
                             settled = true;
                             break;
                         }
-                        nodeId = succs[0]?.id;
+                        nodeId = afterPhase(node.id, succs[0]?.id);
                         break;
                     }
                     case 'decider': {

package/server/dist/{loop-runs-store.js → modules/loops/runtime/loop-runs-store.js}

@@ -260,7 +260,7 @@ function getLoopRun(db, id) {
     return db.prepare('SELECT * FROM loop_runs WHERE id = ?').get(id);
 }
 /** Activity-step count for one event, mirroring the client's deriveFrameActivity
- *  (../../client/src/lib/frame-activity.ts) so the seeded count matches the live
+ *  (../../client/src/features/browser/lib/frame-activity.ts) so the seeded count matches the live
  *  "pasos" the Job panel shows. A single assistant frame may carry several
  *  parallel tool_use blocks → each counts. Non-activity events → 0. */
 function activityStepCount(eventType, payload) {

package/server/dist/{loop-shell-invocation.js → modules/loops/runtime/loop-shell-invocation.js}

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bundledLoopShellInvocation = bundledLoopShellInvocation;
-const bundled_openspec_1 = require("./bundled-openspec");
-const path_resolver_1 = require("./path-resolver");
+const bundled_openspec_1 = require("../../../bundled-openspec");
+const path_resolver_1 = require("../../../path-resolver");
 /** Resolve the exact built-in archive operation without requiring a global CLI. */
 function bundledLoopShellInvocation(command) {
     const match = /^openspec archive ([A-Za-z0-9][A-Za-z0-9._-]*) -y$/.exec(command);

package/server/dist/{loop-step-idle.js → modules/loops/runtime/loop-step-idle.js}

@@ -19,7 +19,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AI_STEP_STALLED_ERROR = exports.LOOP_STEP_IDLE_DEFAULT_MS = void 0;
 exports._resetLoopStepIdleWarningForTests = _resetLoopStepIdleWarningForTests;
 exports.resolveLoopStepIdleTimeoutMs = resolveLoopStepIdleTimeoutMs;
-const stuck_run_detector_1 = require("./stuck-run-detector");
+const stuck_run_detector_1 = require("../../execution/runtime/stuck-run-detector");
 exports.LOOP_STEP_IDLE_DEFAULT_MS = 30 * 60 * 1000;
 /** Error text the executors/engine attach to a stalled step result. */
 exports.AI_STEP_STALLED_ERROR = 'AI step stalled';

package/server/dist/{loop-templates.js → modules/loops/runtime/loop-templates.js}

@@ -128,56 +128,51 @@ function fixLoopGraph(mainPrompts, deciderGoal, maxIterations = 12, timeoutMinut
     return { nodes, edges, config: { maxIterations, timeoutMinutes, ...(aiStepTimeoutMinutes != null ? { aiStepTimeoutMinutes } : {}) } };
 }
 // ── OpenSpec lifecycle loop ──────────────────────────────────────────────────
-// Lightweight lifecycle: prepare → apply/test → validate artifacts → archive.
+// Lightweight lifecycle: prepare → preflight → apply/test → validate artifacts → archive.
 // CLI validation checks OpenSpec artifacts; Apply owns code tests and corrections.
 const OPSX_FF_PROMPT = [
     '{{cmd:opsx:ff}} {{spec.title}}',
-    '',
     '{{spec.description}}',
-    '',
-    'Structured OpenSpec target from the local ticket metadata: "{{spec.openspecChangeName}}". If this value is non-blank, CONTINUE that exact OpenSpec change and do NOT create a duplicate change for the same follow-up. If it is blank and no run change id exists, create a new OpenSpec change from this ticket and generate all required artifacts.',
-    '',
-    'If a run change id appears here — "{{run.changeId}}" — an OpenSpec change for this ticket already exists: CONTINUE that change (do NOT create a new one) and complete its remaining work.',
-    '',
-    'OpenSpec artifacts are authoritative. If the requested implementation changes requirements, acceptance criteria, design decisions, APIs, states, data models, or invariants, amend the relevant OpenSpec artifacts before any code changes.',
-    '',
-    'Do NOT run `openspec archive` in this step, even if the implementation is complete: this loop validates and archives the change itself in later CLI steps, and an archived change makes those steps fail. Leave the change ACTIVE under openspec/changes/<name>/ and name that path in your final reply.',
-    '',
-    'Run fully unattended: make reasonable decisions to keep momentum and NEVER stop to ask — there is no human to answer. When something is unclear, pick the most sensible option, proceed, and note the assumption.',
-].join('\n');
+    'Target: "{{run.changeId}}" takes precedence over ticket metadata "{{spec.openspecChangeName}}". CONTINUE that exact OpenSpec change if active; create it if missing. If both are blank, choose a new name. Do not select unrelated changes or create a duplicate.',
+    'Preparation ONLY: inspect the affected code and generate the required proposal/specs/design/tasks. Do not implement code or run the repository test suite in this phase.',
+    'OpenSpec artifacts are authoritative: map the full requested spec (or each delta/addendum on delivered work) to tasks and an observable acceptance check. Keep artifacts proportional to the change; reference unchanged contracts instead of rewriting them. Do not invent extra work.',
+    'Do NOT run `openspec archive` in this step. Leave the change ACTIVE and name that path in your final reply. Return a concise handoff: change path, affected files, decisions, and checks for Apply; do not repeat the spec or addendum bodies.',
+    'Work unattended within the requested scope. Record assumptions; report a genuine blocker instead of expanding scope.',
+    '{{const:GUARDRAILS}}',
+].join('\n\n');
 const OPSX_APPLY_PROMPT = [
-    '{{cmd:opsx:apply}}',
-    '',
-    'Implement every pending task of the active OpenSpec change for ticket "{{spec.title}}", editing code as needed and marking tasks complete as you finish them.',
-    '',
-    'Before editing code, confirm the active OpenSpec artifacts already describe the contract being implemented. If implementation requires changing requirements, acceptance criteria, design decisions, APIs, states, data models, or invariants, stop code work and amend the OpenSpec artifacts first.',
-    '',
-    'Run the relevant tests and configured checks for the changed behavior, correct failures, and confirm every required task and acceptance criterion is implemented. This step owns code verification; the later CLI validate only checks OpenSpec artifacts. Do not archive here — never run `openspec archive`; the loop archives the change in a later CLI step.',
+    '{{cmd:opsx:apply}} {{run.changeId}}',
+    'Implement the pending tasks of this exact change for "{{spec.title}}". Inspect the diff and tasks first; preserve completed work and keep edits within the requested scope.',
+    'Before editing code, confirm the artifacts describe the requested contract; amend the OpenSpec artifacts first if needed. Do not re-plan the original feature.',
+    'Run the relevant tests for each requested behavior and all repository-required checks. Expand testing for affected contracts or failures. Once checks pass, repeat them only after changes that could invalidate them; do not run unrelated optional suites.',
+    'Inspect the final diff for omissions and regressions, mark completed tasks, and report concrete file/check evidence for every attached addendum. CLI validation checks artifacts, not implementation. Do not archive here — never run `openspec archive`.',
     'Finish with exactly `{{const:VERIFICATION_PASS}}` only after implementation and relevant checks succeed. Otherwise finish with `{{const:VERIFICATION_FAIL}} — <remaining work or failed checks>`.',
-    'Run fully unattended: decide and keep momentum, never pause to ask. If you hit an ambiguity or blocker, make the most reasonable choice, implement it, and continue.',
-].join('\n');
+    '{{const:GUARDRAILS}}',
+].join('\n\n');
 /** The OpenSpec-lifecycle graph (see comment above). Exported for unit testing. */
 function opsxLifecycleGraph() {
     return {
         nodes: [
             { id: 'start', type: 'start', position: { x: COL_X, y: 0 } },
-            { id: 'ff', type: 'ai-step', position: { x: COL_X, y: ROW_GAP * 1 }, data: { label: 'opsx:ff', prompt: OPSX_FF_PROMPT } },
-            { id: 'apply', type: 'ai-step', position: { x: COL_X, y: ROW_GAP * 2 }, data: { label: 'opsx:apply', prompt: OPSX_APPLY_PROMPT, requireVerificationPass: true, stopOnFailure: true } },
-            { id: 'validate', type: 'shell', position: { x: COL_X, y: ROW_GAP * 3 }, data: { label: 'validate', stopOnFailure: true, command: 'openspec validate {{run.changeId}} --type change --strict --no-interactive', requireRunVars: ['changeId'] } },
+            { id: 'ff', type: 'ai-step', position: { x: COL_X, y: ROW_GAP * 1 }, data: { label: 'opsx:ff', prompt: OPSX_FF_PROMPT, stopOnFailure: true } },
+            { id: 'preflight', type: 'shell', position: { x: COL_X, y: ROW_GAP * 2 }, data: { label: 'validate artifacts before implementation', stopOnFailure: true, command: 'openspec validate {{run.changeId}} --type change --strict --no-interactive', requireRunVars: ['changeId'], failureRecovery: { target: 'ff', maxRetries: 1, artifactOnly: true } } },
+            { id: 'apply', type: 'ai-step', position: { x: COL_X, y: ROW_GAP * 3 }, data: { label: 'opsx:apply', prompt: OPSX_APPLY_PROMPT, requireVerificationPass: true, stopOnFailure: true, failureRecovery: { target: 'apply', maxRetries: 1 } } },
+            { id: 'validate', type: 'shell', position: { x: COL_X, y: ROW_GAP * 4 }, data: { label: 'validate', stopOnFailure: true, command: 'openspec validate {{run.changeId}} --type change --strict --no-interactive', requireRunVars: ['changeId'], failureRecovery: { target: 'ff', maxRetries: 1, artifactOnly: true } } },
             // Unattended archive: deterministic CLI, no AI, no prompt. `requireRunVars`
             // makes the engine REFUSE to run if no change id was captured (never archive
             // an unknown change); `openspec archive -y` syncs the main specs by default.
-            { id: 'archive', type: 'shell', position: { x: COL_X, y: ROW_GAP * 4 }, data: { label: 'archive', command: 'openspec archive {{run.changeId}} -y', requireRunVars: ['changeId'] } },
-            { id: 'done', type: 'end', position: { x: COL_X, y: ROW_GAP * 5 }, data: { outcome: 'success' } },
+            { id: 'archive', type: 'shell', position: { x: COL_X, y: ROW_GAP * 5 }, data: { label: 'archive', stopOnFailure: true, failureRecovery: { target: 'archive', maxRetries: 1 }, command: 'openspec archive {{run.changeId}} -y', requireRunVars: ['changeId'] } },
+            { id: 'done', type: 'end', position: { x: COL_X, y: ROW_GAP * 6 }, data: { outcome: 'success' } },
         ],
         edges: [
             { id: 'e-start', source: 'start', target: 'ff' },
-            { id: 'e-ff', source: 'ff', target: 'apply' },
+            { id: 'e-ff', source: 'ff', target: 'preflight' },
+            { id: 'e-preflight', source: 'preflight', target: 'apply' },
             { id: 'e-apply', source: 'apply', target: 'validate' },
             { id: 'e-validate', source: 'validate', target: 'archive' },
             { id: 'e-archive', source: 'archive', target: 'done' },
         ],
-        // This linear lifecycle has no retry cycle. Like the other built-ins,
+        // Phase recovery is bounded per failing node, without an AI Decider. Like the other built-ins,
         // the run is UNTIMED (0 = no timeout) — apply can
         // implement a whole change and must never be killed mid-flight.
         config: { maxIterations: 3, timeoutMinutes: 0, aiStepTimeoutMinutes: 0 },

package/server/dist/{loops-router.js → modules/loops/runtime/loops-router.js}

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerLoopsRoutes = registerLoopsRoutes;
-const ids_1 = require("./ids");
-const feature_flags_1 = require("./feature-flags");
+const ids_1 = require("../../../ids");
+const feature_flags_1 = require("../../../feature-flags");
 const loops_store_1 = require("./loops-store");
 const loop_templates_1 = require("./loop-templates");
 const loop_factory_1 = require("./loop-factory");