specrails-desktop 2.55.1 → 2.56.0

package/client/dist/index.html

@@ -204,7 +204,7 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-BcligJ3-.js"></script>
+    <script type="module" crossorigin src="/assets/index-Cxb288Rj.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-CNC7AqOf.js">
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-zu2_FqZY.js">
     <link rel="modulepreload" crossorigin href="/assets/react-dom-DiWzBDP9.js">

package/docs/internals/adding-a-provider.md

@@ -397,3 +397,10 @@ bundled `local-runner` process, which speaks claude-shaped stream-json so the
 spawn contract is unchanged. If you add another endpoint-backed provider, reuse
 that adapter factory + the runner rather than teaching managers a new
 transport. See `docs/internals/local-agent-runner.md`.
+
+### Claude Opus generation
+
+The `opus` catalog value selects Claude Opus 5.5 (`claude-opus-5-5`). Keep the
+Claude adapter pin, selector labels, Core CLI executor and cost estimates aligned
+when advancing this alias. Concrete historical model IDs in usage events retain
+their existing estimates; provider-reported cost remains authoritative.

package/docs/internals/core-runtime-updates.md

@@ -12,6 +12,11 @@ framework is rejected rather than silently replacing an update.
 
 ## Persistence and publication
 
+The release bundle pins Core 5.6.0 in `desktop-release.yml` and
+`scripts/assemble-bundled-core.lock.json`. This includes scoped runtime recovery
+and the Opus 5.5 alias. Update both pins together and check compatibility against
+the staged published package; retained runs still use their original runtime.
+
 Desktop updates retain the complete npm installation, including dependencies,
 under `~/.specrails/core/<version>/`. The registry home override applies to this
 directory. Only the managed package corresponding to the active framework is

package/docs/internals/programmatic-agent-runtime.md

@@ -138,3 +138,69 @@ Core's additive runtime metrics v1 are passed from compact status to each saved
 Older Core versions continue to work without the panel. The server validates numeric fields and known phase IDs, drops unsupported/malformed metrics and projects only the supported fields; it never forwards arbitrary transcripts from the metrics object. Missing billing is displayed as unavailable rather than zero. Cache tokens are already included in input tokens, and agent duration already includes native tool work. The panel does not estimate savings or measure implementation quality.
 
 The paired `agent-runtime-efficiency` OpenSpec change in specrails-core documents verification ownership, efficient API tools and the measurement contract. Core exposes the same report through `runtime status` / `runtime-result`, so a fixed set of real tasks can be compared without a Desktop database migration.
+
+## Diagnose before retrying
+
+`GET /agent-runtime/runs/:runId/diagnosis` (MCP: `specrails_jobs runtime_diagnose`)
+returns the original scope, historical completed steps, up to eight recent
+failed/interrupted attempts, verification and acceptance reasons, and a recovery
+recommendation. It performs no provider calls or mutations. Repeated matching
+step/error pairs recommend repairing the precondition before retrying. A missing
+history on an older retained Core is unknown, not zero failures.
+
+MCP `runtime_evidence` accepts `evidenceId`, `section`, `sourceId`, `cursor` and
+`limit` to inspect the actual evidence beyond its index. `canResume` only means
+resume is available. Changed receipts can still cause verification and review
+to repeat; no zero-cost promise is made. A succeeded run awaiting settlement
+should use `runtime_settle`, preserving the existing implementation.
+
+Paired Core now preserves OpenSpec's output when archive exits successfully
+without creating its destination, and distinguishes that from multiple matching
+destinations. Retrying a failed archive keeps valid verification/review receipts;
+changed candidate files or environment still require fresh evidence. These Core
+fixes require a newly bundled/released runtime; retained original runtimes are
+not silently replaced or migrated. Diagnosis does not add arbitrary file-write
+access: repairs without a supported scoped tool are reported as concrete manual
+steps instead of being disguised as a reason to relaunch.
+
+## Repair the original worktree
+
+`specrails_recovery` calls `POST /agent-runtime/runs/:runId/recovery` with a
+strict action-specific request. It never constructs a new context/worktree.
+
+| Action | Inputs and permission | Result |
+| --- | --- | --- |
+| inspect | read | Original repository IDs, registered check definitions, recent attempts |
+| list_files / read_file / diff | repositoryId + relative path; read | Bounded directory/line/diff output; read_file includes SHA-256 |
+| history | optional offset; read | Latest attempts first, pages of 20 with nextOffset |
+| patch | repositoryId, path, expectedHash, oldText, newText, operationId UUID, reason; write | One unique replacement in an existing file, atomic publication |
+| check | kind openspec or verification; saved checkId for verification; operationId + reason; destructive | Real validation evidence, bounded output and durable outcome |
+
+Patches are limited to 16 KiB fragments and files readable within 128 KiB.
+Runtime/provider metadata, secret paths, frozen OpenSpec changes/config/archives,
+agent instructions, traversal, symlinks and platform aliases are rejected. New
+files, deletions and arbitrary commands are not supported. Explicit repository IDs
+prevent cross-project resolution. Verification runs one registered command with a
+45-second deadline; full acceptance remains the normal resume/settlement path.
+
+Desktop blocks admission while project executions are active and reserves the
+run/rail. Core takes the same cross-process lease as Resume. An interrupted write
+requires `acknowledgeInterrupted` after inspecting partial changes. Completed or
+archived runs cannot be patched or checked through recovery. Inspection remains
+available. This is an application boundary, not an OS sandbox against unrelated
+processes modifying the worktree concurrently.
+
+Core stores at most 100 attempts in `recovery-history.json` beside the pipeline
+state, separate from checkpoints. Each mutation has a write-ahead operation ID,
+request fingerprint, cause, before/after hashes where relevant and final outcome.
+Reuse the exact request/ID after transport uncertainty. A pending patch whose
+after-hash is present is reconciled; other pending operations become interrupted
+and are not rerun. Repeating a failed check on unchanged candidate code requires
+a documented `changedPrecondition`; this records the operator's explanation, not
+an independent proof that an external prerequisite changed.
+
+Resume still enforces verification, review and acceptance. Scoped verification
+uses Core's existing evidence/receipt store and cannot mark workflow phases done.
+OpenSpec checks validate real files without copying or archiving them. Old retained
+Core packages lacking `scopedRecovery` are not upgraded/migrated behind the run's
+back: the tool returns a manual-repair limitation rather than recommending Relaunch.

package/docs/internals/source-map.md

@@ -5,7 +5,7 @@ architectural dependency declaration. Search a heading or filename and read only
 the relevant source and tests. Feature prefixes group the legacy server files;
 new bounded modules live under `server/modules/`.
 
-Includes 940 source/build files. Nearby tests are linked where names
+Includes 942 source/build files. Nearby tests are linked where names
 match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 ## cli
@@ -979,6 +979,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [plugins.ts](../../server/mcp/tools/plugins.ts) · [test](../../server/mcp/tools/plugins.test.ts)
 - [projects.ts](../../server/mcp/tools/projects.ts)
 - [rails.ts](../../server/mcp/tools/rails.ts)
+- [recovery.ts](../../server/mcp/tools/recovery.ts) · [test](../../server/mcp/tools/recovery.test.ts)
 - [setup.ts](../../server/mcp/tools/setup.ts) · [test](../../server/mcp/tools/setup.test.ts)
 - [specs.ts](../../server/mcp/tools/specs.ts) · [test](../../server/mcp/tools/specs.test.ts)
 - [support.ts](../../server/mcp/tools/support.ts)
@@ -1031,6 +1032,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [agent-runtime-metrics.ts](../../server/modules/agent-runtime/runtime/agent-runtime-metrics.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-metrics.test.ts)
 - [agent-runtime-package.ts](../../server/modules/agent-runtime/runtime/agent-runtime-package.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-package.test.ts)
 - [agent-runtime-paths.ts](../../server/modules/agent-runtime/runtime/agent-runtime-paths.ts)
+- [agent-runtime-recovery.ts](../../server/modules/agent-runtime/runtime/agent-runtime-recovery.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-recovery.test.ts)
 - [agent-runtime-repositories.ts](../../server/modules/agent-runtime/runtime/agent-runtime-repositories.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-repositories.test.ts)
 - [agent-runtime-settings-router.ts](../../server/modules/agent-runtime/runtime/agent-runtime-settings-router.ts)
 - [agent-runtime-settings.ts](../../server/modules/agent-runtime/runtime/agent-runtime-settings.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-settings.test.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.55.1",
+  "version": "2.56.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/mcp/guide.js

@@ -342,16 +342,30 @@ can run Contract Refine require AI-spawn, including Explore conversions.
   trace or import is usually relative to a subdirectory), \`search\` (literal
   content search with line numbers and bounded snippets), \`read_file\`
   (bounded line ranges with continuation metadata),
-  \`summary\`, \`provenance\`, \`diff\`. There is no MCP write path to files.
+  \`summary\`, \`provenance\`, \`diff\`. General Code Explorer remains read-only; stopped-run repairs use specrails_recovery.
   Start with content search to find behavior and tests, then read exact ranges.
   Truncated scans or skipped files do not prove that a symbol is absent.
-- **Run failures & recovery**: \`specrails_jobs(runtime_runs, jobId)\` reads
+- **Run failures & recovery**: Start with \`specrails_jobs(runtime_diagnose, jobId)\`
+  for original scope, completed steps, repeated failures and receipt validity.
+  Availability of Resume is not a repair recommendation. After the same failure,
+  identify and validate a changed precondition before retrying; do not default
+  to Relaunch. Evidence can be paged with evidenceId/section/sourceId/cursor/limit.
+  \`specrails_jobs(runtime_runs, jobId)\` reads
   why a run stopped and what it offers (\`canResume\`, \`recoverableSteps\`,
   \`pendingApproval\`, \`pendingQuestion\`); \`runtime_evidence\` the durable
   evidence. Act only on the user's confirmation: \`runtime_resume\` /
   \`runtime_recover\` (ai-spawn), \`runtime_approve\` / \`runtime_settle\` /
   \`runtime_dismiss\` (write), \`runtime_cancel\` (destructive). In the in-app
   mission, a failed run also updates its card and posts a briefing turn.
+- **Scoped repair**: \`specrails_recovery\` inspects/list_files/read_file/diff/history
+  in the original run scope. \`patch\` requires write permission, a current
+  expectedHash, a unique fragment, reason and operationId. \`check\` requires
+  destructive permission because registered verification executes project code;
+  select a saved checkId from inspect or kind openspec. No arbitrary commands,
+  frozen plan edits, checkpoint changes, deletes or automatic resume. Read the
+  durable outcome; reuse operationId on uncertain transport and explain a real
+  changedPrecondition before retrying a failed check. Old retained Core packages
+  may lack this capability; never silently migrate them.
 - **Execution evidence**: \`specrails_jobs(phase_breakdown)\` explains phases;
   job events are paginated. \`specrails_rails(pr_candidates)\` finds existing
   PR targets; \`review_packet(prDeliveryId)\` reads verification evidence.

package/server/dist/mcp/tools/catalog.js

@@ -8,6 +8,7 @@ const meta_1 = require("./meta");
 const specs_1 = require("./specs");
 const rails_1 = require("./rails");
 const jobs_1 = require("./jobs");
+const recovery_1 = require("./recovery");
 const chat_1 = require("./chat");
 const agents_1 = require("./agents");
 const plugins_1 = require("./plugins");
@@ -38,6 +39,7 @@ function buildToolSpecs() {
     specs.push(...(0, specs_1.specsTools)());
     specs.push(...(0, rails_1.railsTools)());
     specs.push(...(0, jobs_1.jobsTools)());
+    specs.push(...(0, recovery_1.recoveryTools)());
     specs.push(...(0, chat_1.chatTools)());
     specs.push(...(0, agents_1.agentsTools)());
     specs.push(...(0, plugins_1.pluginsTools)());

package/server/dist/mcp/tools/jobs.js

@@ -39,7 +39,8 @@ function jobsTools() {
                 'interactive_turn (ai-spawn — send a steering prompt to any running interactive job; claude jobs are interactive by default), ' +
                 'finalize (settle a running interactive job now — Freestyle jobs otherwise wait for it, others auto-settle), ' +
                 'runtime_runs (read the programmatic runtime state of jobId — or every run when omitted — status, nextStep, canResume, recoverableSteps, pendingApproval, pendingQuestion; THIS is how you learn why a run failed and what recovery it offers), ' +
-                'runtime_evidence (read the durable runtime evidence of jobId), ' +
+                'runtime_diagnose (read-only recovery assessment for jobId: original scope, completed steps, repeated failures and verification invalidation reasons; use before recommending retry or relaunch), ' +
+                'runtime_evidence (read the durable runtime evidence of jobId; page with evidenceId/section/sourceId/cursor/limit), ' +
                 'runtime_resume (ai-spawn — continue a resumable run: optional approve/recover/invalidate step-id lists + answer for a pending question; act ONLY after the user confirmed on the card), ' +
                 'runtime_recover (ai-spawn — shorthand for runtime_resume with recover:[stepIds] over the recoverable steps), ' +
                 'runtime_approve (write — shorthand for runtime_resume with approve:[stepId] for a pending approval), ' +
@@ -86,6 +87,7 @@ function jobsTools() {
                     'background_logs',
                     'background_kill',
                     'runtime_runs',
+                    'runtime_diagnose',
                     'runtime_evidence',
                     'runtime_resume',
                     'runtime_recover',
@@ -102,7 +104,7 @@ function jobsTools() {
                     .optional()
                     .describe('Job id (for get / cancel / priority / diagnostic / interactive_turn / finalize)'),
                 // ── list / export pagination + filters ──
-                limit: zod_1.z.number().int().positive().max(200).optional().describe('Page size for list (1-200, default 50) / activity (1-100, default 50); background_logs returns the last N buffered log lines'),
+                limit: zod_1.z.number().int().positive().max(200).optional().describe('Page size for list (1-200, default 50) / activity (1-100, default 50) / runtime_evidence (1-100, default 25); background_logs returns the last N buffered log lines'),
                 offset: zod_1.z.number().int().nonnegative().optional().describe('Page offset for list/background_list'),
                 eventLimit: zod_1.z.number().int().positive().max(200).optional().describe('get: maximum persisted events to return (default 50, latest events by default)'),
                 eventOffset: zod_1.z.number().int().nonnegative().optional().describe('get: chronological event offset; omit for the latest eventLimit events'),
@@ -151,6 +153,10 @@ function jobsTools() {
                 invalidate: zod_1.z.array(zod_1.z.string()).optional().describe('runtime_resume: step ids whose results must be discarded before continuing'),
                 answer: zod_1.z.string().optional().describe('runtime_resume: the answer to the run\'s pending question'),
                 stepId: zod_1.z.string().optional().describe('runtime_approve/runtime_recover: the single step id (alternative to the arrays)'),
+                evidenceId: zod_1.z.string().max(1024).optional().describe('runtime_evidence: verification evidence id returned by the index'),
+                section: zod_1.z.enum(['summary', 'stdout', 'stderr', 'source']).optional().describe('runtime_evidence: summary index, command output or recorded source'),
+                sourceId: zod_1.z.string().max(1024).optional().describe('runtime_evidence: source id returned by the evidence index'),
+                cursor: zod_1.z.string().max(1024).optional().describe('runtime_evidence: continuation cursor returned by the previous page'),
             },
             async handler(ctx, args) {
                 const base = (0, types_1.projectPath)(ctx, args.projectId);
@@ -350,11 +356,23 @@ function jobsTools() {
                         const railIndex = args.railIndex;
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs${typeof railIndex === 'number' ? `?railIndex=${railIndex}` : ''}`);
                     }
+                    case 'runtime_diagnose': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('runtime_diagnose requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/diagnosis`);
+                    }
                     case 'runtime_evidence': {
                         const id = args.jobId;
                         if (!id)
                             throw new Error('runtime_evidence requires a "jobId".');
-                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/evidence`);
+                        const query = new URLSearchParams();
+                        if (typeof args.evidenceId === 'string')
+                            query.set('id', args.evidenceId);
+                        for (const key of ['section', 'sourceId', 'cursor', 'limit'])
+                            if (args[key] !== undefined)
+                                query.set(key, String(args[key]));
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/evidence${query.size ? '?' + query.toString() : ''}`);
                     }
                     case 'runtime_resume':
                     case 'runtime_recover':
@@ -371,7 +389,7 @@ function jobsTools() {
                                 recover = state.runs?.[0]?.recoverableSteps ?? [];
                             }
                             if (!recover.length)
-                                throw new Error('runtime_recover: the run has no recoverable steps — read runtime_runs and use runtime_resume instead.');
+                                throw new Error('runtime_recover: the run has no interrupted steps to recover — read runtime_diagnose before deciding whether a repair or resume is appropriate.');
                             body.recover = recover;
                         }
                         else if (action === 'runtime_approve') {

package/server/dist/mcp/tools/recovery.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoveryTools = recoveryTools;
+const zod_1 = require("zod");
+const agent_runtime_recovery_1 = require("../../modules/agent-runtime/runtime/agent-runtime-recovery");
+const types_1 = require("./types");
+function recoveryTools() {
+    return [{
+            name: 'specrails_recovery', title: 'Repair a stopped run', hintTier: 'read',
+            description: 'Inspect and repair the ORIGINAL saved run worktree without relaunching implementation. Actions: inspect (repositories, registered checks, recent repairs), list_files, read_file (paged lines + SHA-256), diff, history, patch (one exact unique replacement in an existing file, mandatory expectedHash and operationId), check (OpenSpec validation or ONE checkId returned by inspect). Patch requires write permission. Check executes project code and requires destructive permission. No arbitrary shell, checkpoint edits, frozen plan edits, file deletion or automatic resume. Reuse operationId after transport uncertainty; never blindly repeat failed checks. Read history and state a changedPrecondition before repeating a failed check on unchanged code. After successful repair/check use specrails_jobs runtime_resume under its normal authorization and verify the terminal outcome.',
+            tier: args => args.action === 'check' ? 'destructive' : args.action === 'patch' ? 'write' : 'read',
+            inputSchema: {
+                action: zod_1.z.enum(['inspect', 'list_files', 'read_file', 'diff', 'history', 'patch', 'check']),
+                projectId: zod_1.z.string().optional(), jobId: zod_1.z.string().min(1),
+                repositoryId: zod_1.z.string().optional().describe('Exact membership returned by inspect; required for file actions'),
+                path: zod_1.z.string().optional().describe('Repository-relative path; list_files accepts .'),
+                startLine: zod_1.z.number().int().positive().optional(), endLine: zod_1.z.number().int().positive().optional(),
+                offset: zod_1.z.number().int().nonnegative().optional().describe('history only: nextOffset from the previous page; newest attempts first'),
+                expectedHash: zod_1.z.string().optional().describe('Full-file hash returned by read_file, mandatory for patch'),
+                oldText: zod_1.z.string().optional(), newText: zod_1.z.string().optional(),
+                operationId: zod_1.z.string().uuid().optional().describe('New UUID per patch/check; reuse with the exact same request after uncertain transport'),
+                reason: zod_1.z.string().optional().describe('Specific diagnosed cause and purpose of the repair/check'),
+                kind: zod_1.z.enum(['openspec', 'verification']).optional(), checkId: zod_1.z.string().optional(),
+                changedPrecondition: zod_1.z.string().optional().describe('What changed since the failed check; required before repeating an unchanged candidate'),
+                acknowledgeInterrupted: zod_1.z.boolean().optional().describe('Only after inspecting and accepting the partial writes of an interrupted run'),
+            },
+            async handler(ctx, args) {
+                const { projectId, jobId, ...request } = args;
+                const body = agent_runtime_recovery_1.recoveryRequestSchema.parse(request);
+                if (typeof jobId !== 'string' || !jobId)
+                    throw new Error('Scoped recovery requires jobId');
+                return (0, types_1.apiCall)(ctx, 'POST', `${(0, types_1.projectPath)(ctx, projectId)}/agent-runtime/runs/${encodeURIComponent(jobId)}/recovery`, body);
+            },
+        }];
+}

package/server/dist/mcp/tools/support.js

@@ -244,7 +244,10 @@ function nextSteps(topic) {
             ];
         case 'rails_jobs':
             return [
-                'Use read tools for rails/jobs status before guessing: specrails_rails, specrails_jobs, and specrails_watch only when the user asks to wait.',
+                'Read specrails_jobs runtime_diagnose for the failed job before recommending recovery; inspect runtime_evidence and original-worktree scope, not just the error label.',
+                'If a step fails repeatedly, identify the prerequisite or artifact that must change and validate the smallest repair before retrying. canResume is not proof a retry will work. Relaunch is only justified by evidence that the original run cannot continue safely.',
+                'Use specrails_recovery inspect/read_file/diff, then a hash-guarded patch and registered check for authorized small repairs in the original worktree. Read history and preserve operationId on uncertain transport.',
+                'Preserve completed implementation. Use runtime_settle for a succeeded run awaiting delivery; name unsupported repair capabilities instead of proposing a fresh implementation.',
                 'For a failed or stuck job, inspect the Job Detail logs and report the real failure.',
                 'Do not relaunch or stop anything without confirmation and the required permission level.',
             ];

package/server/dist/modules/accounting/runtime/pricing.js

@@ -69,9 +69,13 @@ exports.PRICING = {
     // usage is the sole signal. Keys are the CLI's short aliases; full model ids
     // (e.g. per-event `message.model` like "claude-sonnet-4-6") are collapsed by
     // family via `resolvePriceEntry`. Cache write = 1.25x input (5-minute-TTL
-    // default), cache read = 0.1x input. Anthropic usage semantics: input_tokens
+    // default); cache reads are model-specific (Opus 5.5 uses 0.05x input).
+    // Anthropic usage semantics: input_tokens
     // EXCLUDES cache reads/writes → inputIncludesCacheReads: false.
-    'claude:opus': { inputPer1M: 5.00, outputPer1M: 25.00, cacheReadPer1M: 0.50, cacheWritePer1M: 6.25, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
+    'claude:claude-opus-5': { inputPer1M: 5.00, outputPer1M: 25.00, cacheReadPer1M: 0.50, cacheWritePer1M: 6.25, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
+    // Opus 5.5: https://platform.claude.com/docs/en/models/opus-5-5/overview
+    'claude:opus': { inputPer1M: 4.00, outputPer1M: 20.00, cacheReadPer1M: 0.20, cacheWritePer1M: 5.00, inputIncludesCacheReads: false, lastReviewedAt: '2026-09-24' },
+    'claude:claude-opus-5-5': { inputPer1M: 4.00, outputPer1M: 20.00, cacheReadPer1M: 0.20, cacheWritePer1M: 5.00, inputIncludesCacheReads: false, lastReviewedAt: '2026-09-24' },
     'claude:sonnet': { inputPer1M: 3.00, outputPer1M: 15.00, cacheReadPer1M: 0.30, cacheWritePer1M: 3.75, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
     'claude:haiku': { inputPer1M: 1.00, outputPer1M: 5.00, cacheReadPer1M: 0.10, cacheWritePer1M: 1.25, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
     'claude:fable': { inputPer1M: 10.00, outputPer1M: 50.00, cacheReadPer1M: 1.00, cacheWritePer1M: 12.50, inputIncludesCacheReads: false, lastReviewedAt: '2026-07-02' },
@@ -89,6 +93,9 @@ function resolvePriceEntry(providerId, model) {
     if (exact)
         return exact;
     if (providerId === 'claude') {
+        // Keep the existing estimates for older concrete Opus generations.
+        if (/^claude-opus-(?:4(?:-|$)|5$)/.test(model))
+            return exports.PRICING['claude:claude-opus-5'];
         const family = CLAUDE_MODEL_FAMILY.exec(model);
         if (family)
             return exports.PRICING[`claude:${family[1]}`];

package/server/dist/modules/agent-runtime/runtime/agent-runtime-controls-router.js

@@ -83,6 +83,14 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
             res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 503).json({ error: 'evidence_unavailable', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'The original runtime evidence is unavailable' });
         }
     });
+    router.get('/:projectId/agent-runtime/runs/:runId/diagnosis', async (req, res) => {
+        try {
+            res.json(await controls(req).diagnose(String(req.params.runId)));
+        }
+        catch (error) {
+            res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 503).json({ error: 'diagnosis_unavailable', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'Could not inspect the original runtime execution' });
+        }
+    });
     router.post('/:projectId/agent-runtime/runs/:runId/resume', async (req, res) => {
         try {
             await controls(req).resume(String(req.params.runId), (0, agent_runtime_controls_1.validateRuntimeResumeInput)(req.body));
@@ -92,6 +100,14 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
             res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 500).json({ error: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.code : 'runtime_resume_failed', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'Could not resume runtime execution' });
         }
     });
+    router.post('/:projectId/agent-runtime/runs/:runId/recovery', async (req, res) => {
+        try {
+            res.json(await controls(req).recovery(String(req.params.runId), req.body));
+        }
+        catch (error) {
+            res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 500).json({ error: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.code : 'runtime_recovery_failed', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'Could not perform scoped recovery' });
+        }
+    });
     router.post('/:projectId/agent-runtime/runs/:runId/settle', async (req, res) => {
         try {
             await controls(req).settle(String(req.params.runId));

package/server/dist/modules/agent-runtime/runtime/agent-runtime-controls.js

@@ -25,6 +25,7 @@ const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
 const multi_repo_execution_store_1 = require("../../delivery/runtime/multi-repo-execution-store");
 const db_1 = require("../../../db");
 const loop_run_manager_1 = require("../../loops/runtime/loop-run-manager");
+const agent_runtime_recovery_1 = require("./agent-runtime-recovery");
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const STEP_IDS = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
 const ANSWER_LIMIT = 20_000;
@@ -94,7 +95,7 @@ async function readAgentRuntimeStatus(contextPath, cwd, env) {
         selection = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-selection.json'), 'utf8'));
     }
     catch { /* Original hosts may not record selection origins. */ }
-    return result.state ? { ...result.state, efficiencySummary: (0, agent_runtime_metrics_1.applyRuntimeSelectionOrigins)((0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(result.efficiencySummary), selection, result.state.runId) } : null;
+    return result.state ? { ...result.state, inspection: result.pipeline, efficiencySummary: (0, agent_runtime_metrics_1.applyRuntimeSelectionOrigins)((0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(result.efficiencySummary), selection, result.state.runId) } : null;
 }
 /** One controller per ProjectContext; Core's durable lease remains the final
  * cross-process guard. Resume never constructs a new context or worktree. */
@@ -165,6 +166,97 @@ class AgentRuntimeControls {
             throw new RuntimeControlError(503, 'evidence_unavailable', 'Core evidence is unavailable or incompatible');
         return result;
     }
+    async recovery(runId, input) {
+        const parsed = agent_runtime_recovery_1.recoveryRequestSchema.safeParse(input);
+        if (!parsed.success)
+            throw new RuntimeControlError(400, 'invalid_recovery_request', parsed.error.message);
+        if (this.disposed)
+            throw new RuntimeControlError(503, 'runtime_shutting_down', 'Project runtime is shutting down');
+        const parent = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
+        const idle = () => parent?.status === 'completed' && !this.ctx.railLoopRuns?.size && !this.ctx.railJobs?.size
+            && !this.ctx.db.prepare("SELECT 1 FROM jobs WHERE status = 'running' LIMIT 1").get();
+        if (!idle() || this.active.size)
+            throw new RuntimeControlError(409, 'runtime_run_active', 'Wait for project executions to settle before scoped recovery');
+        const context = this.context(runId);
+        const active = { cancelled: false };
+        this.active.set(runId, active);
+        if (parent?.rail_index != null)
+            this.ctx.railLoopRuns?.set(runId, { railIndex: parent.rail_index, ticketIds: [], requiresTerminalIntent: true });
+        try {
+            const result = await (this.dependencies.recovery ?? agent_runtime_recovery_1.invokeRuntimeRecovery)({ contextPath: context.file, cwd: context.cwd, env: context.env, request: parsed.data,
+                onSpawn: child => { active.child = child; if (active.cancelled || this.disposed)
+                    this.cancel(runId); },
+            });
+            if (parsed.data.action === 'patch' || parsed.data.action === 'check') {
+                this.statusCache.delete(runId);
+                this.ctx.db.transaction(() => {
+                    const seq = this.ctx.db.prepare('SELECT COALESCE(MAX(seq), -1) + 1 AS seq FROM events WHERE job_id = ?').get(runId).seq;
+                    (0, db_1.appendEvent)(this.ctx.db, runId, seq, { event_type: 'runtime-recovery', source: 'stdout', payload: JSON.stringify({ action: parsed.data.action, result }) });
+                })();
+            }
+            return result;
+        }
+        catch (error) {
+            if (error instanceof RuntimeControlError)
+                throw error;
+            throw new RuntimeControlError(409, 'runtime_recovery_blocked', error instanceof Error ? error.message : 'Recovery failed; inspect history before retrying');
+        }
+        finally {
+            clearTimeout(active.forceKillTimer);
+            this.active.delete(runId);
+            this.ctx.railLoopRuns?.delete(runId);
+            this.statusCache.delete(runId);
+        }
+    }
+    /** Read-only recovery assessment. canResume is admission, not a repair claim. */
+    async diagnose(runId) {
+        const summary = await this.summary(runId);
+        if (summary.historical || summary.status === 'unavailable')
+            return {
+                runId, summary, recommendation: 'inspect_saved_evidence',
+                reason: 'Live original runtime scope is unavailable. Preserve saved work and inspect the missing scope before proposing a fresh run.',
+                repeatFailureCount: null, recentFailures: [],
+            };
+        const { file, frozen, cwd, env } = this.context(runId);
+        const state = await this.dependencies.status(file, cwd, env);
+        if (!state || state.runId !== runId)
+            throw new RuntimeControlError(409, 'runtime_state_unavailable', 'No saved workflow state is available');
+        const failures = (state.recentFailures ?? []).slice(-8).map(item => ({ stepId: item.stepId, status: item.status, at: item.at, error: item.error?.slice(-6000) }));
+        const matching = failures.filter(item => item.status === 'failed' && item.stepId === state.nextStep && !!item.error && item.error === state.error?.slice(-6000));
+        const repeated = matching.length > 1;
+        const recommendation = summary.active ? 'wait_for_active_run'
+            : summary.canSettle ? 'prepare_delivery'
+                : summary.status === 'succeeded' ? 'inspect_delivery'
+                    : summary.pendingQuestion ? 'answer_question'
+                        : summary.pendingApproval ? 'inspect_and_approve'
+                            : repeated ? 'repair_before_retry'
+                                : summary.recoverableSteps.length ? 'inspect_interrupted_writes'
+                                    : 'diagnose_before_retry';
+        return {
+            runId, summary, recommendation,
+            reason: {
+                wait_for_active_run: 'The original run is still active. Inspect its progress instead of starting a competing execution.',
+                prepare_delivery: 'Core succeeded but Desktop settlement is still pending. Prepare delivery of the existing implementation.',
+                inspect_delivery: 'Core already succeeded. Inspect the delivery state rather than restarting implementation.',
+                answer_question: 'The run is waiting for the recorded question to be answered.',
+                inspect_and_approve: 'The run is waiting for approval of the recorded candidate; inspect its evidence first.',
+                repair_before_retry: 'The same step failed with the same error more than once. Identify and verify a changed precondition before spending on another attempt.',
+                inspect_interrupted_writes: 'An interrupted step may have partially changed files. Inspect the original worktree before explicitly recovering it.',
+                diagnose_before_retry: 'Determine the failing precondition from the saved evidence. A resumable run may still need a repair; a fresh run is not a diagnosis.',
+            }[recommendation],
+            originalScope: { artifactRoot: frozen.artifactRoot, repositories: frozen.repositories },
+            completedSteps: Object.entries(state.steps).filter(([, step]) => step.status === 'succeeded').map(([id]) => id),
+            recentFailures: failures, repeatFailureCount: state.recentFailures ? matching.length : null,
+            verification: state.inspection?.verification ? { valid: state.inspection.verification.valid, reasons: state.inspection.verification.reasons } : null,
+            acceptance: state.inspection?.acceptance ? { valid: state.inspection.acceptance.valid, reasons: state.inspection.acceptance.reasons } : null,
+            resumePhase: state.inspection?.resumePhase ?? null,
+            limitations: [
+                'Recent failure history is bounded to eight attempts; null means the retained Core does not expose it.',
+                'Completed steps are historical outcomes. Resume revalidates receipts and may repeat verification/review after changes; do not promise zero cost.',
+                'This diagnostic does not execute repairs, resume, relaunch, publish or discard work.',
+            ],
+        };
+    }
     async list() {
         const directory = node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(this.ctx.project).specrailsDir, 'pipeline');
         if (!node_fs_1.default.existsSync(directory))

package/server/dist/modules/agent-runtime/runtime/agent-runtime-recovery.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoveryRequestSchema = void 0;
+exports.invokeRuntimeRecovery = invokeRuntimeRecovery;
+const node_child_process_1 = require("node:child_process");
+const zod_1 = require("zod");
+const agent_runtime_package_1 = require("./agent-runtime-package");
+const core_node_runtime_1 = require("../../../core-node-runtime");
+const win_spawn_1 = require("../../../util/win-spawn");
+// Desktop validates its HTTP contract; retained Core independently validates
+// the same operation at the filesystem/lease boundary.
+const file = { repositoryId: zod_1.z.string().min(1).max(128), path: zod_1.z.string().min(1).max(1024) };
+const operation = { operationId: zod_1.z.string().uuid(), reason: zod_1.z.string().trim().min(1).max(2000), acknowledgeInterrupted: zod_1.z.boolean().optional(), changedPrecondition: zod_1.z.string().trim().min(1).max(2000).optional() };
+exports.recoveryRequestSchema = zod_1.z.discriminatedUnion('action', [
+    zod_1.z.object({ action: zod_1.z.literal('inspect') }).strict(),
+    zod_1.z.object({ action: zod_1.z.literal('history'), offset: zod_1.z.number().int().nonnegative().optional() }).strict(),
+    zod_1.z.object({ action: zod_1.z.literal('list_files'), ...file }).strict(),
+    zod_1.z.object({ action: zod_1.z.literal('read_file'), ...file, startLine: zod_1.z.number().int().positive().optional(), endLine: zod_1.z.number().int().positive().optional() }).strict(),
+    zod_1.z.object({ action: zod_1.z.literal('diff'), ...file }).strict(),
+    zod_1.z.object({ action: zod_1.z.literal('patch'), ...file, ...operation, expectedHash: zod_1.z.string().regex(/^[a-f0-9]{64}$/), oldText: zod_1.z.string().min(1).max(16_384), newText: zod_1.z.string().max(16_384) }).strict(),
+    zod_1.z.object({ action: zod_1.z.literal('check'), ...operation, kind: zod_1.z.enum(['openspec', 'verification']), checkId: zod_1.z.string().min(1).max(256).optional() }).strict(),
+]);
+async function invokeRuntimeRecovery(input) {
+    const cli = (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(input.contextPath);
+    const invoke = (args, stdin) => new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.execFile)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [cli, ...args], {
+            cwd: input.cwd, env: (0, win_spawn_1.windowsSpawnEnv)(input.env), windowsHide: true,
+            timeout: stdin ? 65_000 : 15_000, maxBuffer: 2 * 1024 * 1024, encoding: 'utf8',
+        }, (error, stdout) => {
+            if (!error) {
+                resolve(stdout);
+                return;
+            }
+            let detail = 'Recovery did not complete; inspect its history before retrying with the same operationId.';
+            try {
+                const parsed = JSON.parse(stdout);
+                if (typeof parsed.error === 'string')
+                    detail = parsed.error.slice(-6000);
+            }
+            catch { /* Do not misrepresent an uncertain transport outcome. */ }
+            reject(new Error(detail));
+        });
+        input.onSpawn?.(child);
+        child.stdin?.end(stdin ?? '');
+    });
+    const api = JSON.parse(await invoke(['api']));
+    if (api.capabilities?.scopedRecovery !== 1)
+        throw new Error('The retained original Core does not support scoped recovery. Preserve this run; use a manual repair in its original worktree. Do not replace its runtime or relaunch to bypass this limit.');
+    const response = JSON.parse(await invoke(['recovery', '--context', input.contextPath, '--stdin'], JSON.stringify(input.request)));
+    if (response.type !== 'runtime-recovery' || response.schemaVersion !== 1 || !('result' in response))
+        throw new Error('Invalid Core recovery response; inspect recovery history before retrying');
+    return response.result;
+}

package/server/dist/modules/missions/runtime/agent-failure-briefing.js

@@ -48,7 +48,9 @@ function buildFailureBriefing(input) {
     const lines = [];
     lines.push('[Specrails run-failure briefing — automatic, not typed by the user]');
     lines.push('');
-    lines.push(`${railLabel(input.railIndex, input.railName)} · run ${input.runId} stopped: ${describeFailureCode(input.failure.code)}.`);
+    const description = input.failure.code === 'implementation_failed' && input.failure.stepId
+        ? `the ${input.failure.stepId} step failed` : describeFailureCode(input.failure.code);
+    lines.push(`${railLabel(input.railIndex, input.railName)} · run ${input.runId} stopped: ${description}.`);
     lines.push(`Specs: ${specs.join(', ') || 'none'}.`);
     if (input.failure.stepId)
         lines.push(`Failed step: ${input.failure.stepId}.`);
@@ -81,7 +83,7 @@ function buildFailureBriefing(input) {
     if (input.prDeliveryId)
         lines.push(`Delivery id: ${input.prDeliveryId}.`);
     lines.push('');
-    lines.push('Conduct: explain the failure in at most 6 short lines, name the ONE next action you recommend and why, and stop. Do NOT relaunch, resume or discard by yourself — the user decides on the card. If you need evidence, read it with specrails_jobs (get / runtime_runs / runtime_evidence) before answering.');
+    lines.push('Conduct: explain the failure in at most 6 short lines, name the ONE next action you recommend and why, and stop. Do NOT relaunch, resume or discard by yourself — the user decides on the card. Read specrails_jobs runtime_diagnose and, as needed, get / runtime_evidence before recommending recovery. canResume is not proof that retry fixes the cause. The next action may be diagnosis or a targeted repair, not a card button. If the same failure recurred, identify what must change before another attempt; do not default to Relaunch. This six-line limit applies only to this automatic turn.');
     return lines.join('\n');
 }
 /** The context ref persisted on the briefing row so the client renders it compactly. */