@ornexus/neocortex 4.60.66 → 4.60.68

package/packages/client/dist/resolvers/local-resolver.js

@@ -1,8 +1,255 @@
-import{readFile as f,access as d}from"node:fs/promises";import{join as h,resolve as y}from"node:path";import{ResolverMode as w}from"../types/index.js";const v=/^---\n([\s\S]*?)\n---/;function u(p){const t=p.match(v);if(!t)return{frontmatter:{},body:p};const s={},e=t[1].split(`
-`);for(const o of e){const n=o.indexOf(":");if(n===-1)continue;const a=o.slice(0,n).trim().replace(/^['"]|['"]$/g,"");let r=o.slice(n+1).trim();typeof r=="string"&&(r=r.replace(/^['"]|['"]$/g,"")),r==="true"?r=!0:r==="false"&&(r=!1),s[a]=r}const c=p.slice(t[0].length).trimStart();return{frontmatter:s,body:c}}class P{mode=w.LOCAL;projectRoot;stepPathIndex;constructor(t){this.projectRoot=y(t.projectRoot)}async resolveStep(t,s){const e=(await this.resolveStepPathIndex()).get(t);if(!e)throw new Error(`Step '${t}' is not present in the canonical registry`);const c=h(this.projectRoot,e),o=await f(c,"utf-8"),{frontmatter:n,body:a}=u(o);return{id:t,content:a,frontmatter:n}}resolveStepPathIndex(){return this.stepPathIndex??=this.loadStepPathIndex(),this.stepPathIndex}async loadStepPathIndex(){const t=h(this.projectRoot,"core","data","step-registry.json"),s=JSON.parse(await f(t,"utf8")),e=new Map,c=s.asset_bootstrap;if(c&&typeof c=="object"&&!Array.isArray(c)){const o=c.assets;if(!Array.isArray(o))throw new Error("manifest-generation-mismatch");for(const n of o){if(!n||typeof n!="object"||Array.isArray(n))throw new Error("manifest-schema-invalid");const a=n;if(a.type!=="step")continue;const r=a.relative_path;if(typeof r!="string"||!r.startsWith("steps/")||r.includes(".."))throw new Error("manifest-schema-invalid");const i=`core/${r}`,{frontmatter:l}=u(await f(h(this.projectRoot,i),"utf8")),m=l.id;if(typeof m!="string"||!/^step-[a-z0-9][a-z0-9._-]*$/.test(m))throw new Error("manifest-required-step-unresolved");if(e.has(m))throw new Error("manifest-duplicate-reference");e.set(m,i)}}else{const o=s.steps;if(!o||typeof o!="object"||Array.isArray(o))throw new Error("manifest-generation-mismatch");for(const n of Object.values(o))if(Array.isArray(n))for(const a of n){if(!a||typeof a!="object"||Array.isArray(a))throw new Error("manifest-schema-invalid");const r=a,i=r.id,l=r.file;if(typeof i!="string"||typeof l!="string"||!l.startsWith("core/steps/")||l.includes(".."))throw new Error("manifest-schema-invalid");if(e.has(i))throw new Error("manifest-duplicate-reference");e.set(i,l)}}if(e.size===0)throw new Error("manifest-generation-mismatch");return e}async resolveSkill(t,s){const e=[`core/skills/${t}.md`,`core/skills/step-skills/${t}.md`];t.includes("/")&&(e.unshift(`core/skills/step-skills/${t}.md`),e.unshift(`core/skills/${t}.md`));let c=null,o="";for(const r of e){const i=h(this.projectRoot,r);try{c=await f(i,"utf-8"),o=r;break}catch{}}if(c===null)throw new Error(`Skill '${t}' not found. Searched: ${e.join(", ")}`);const{frontmatter:n,body:a}=u(c);return{id:t,content:a,metadata:{...n,resolvedPath:o}}}async resolveStandard(t){const s=h(this.projectRoot,"core","standards",t);let e;try{e=await f(s,"utf-8")}catch{if(!t.endsWith(".md"))e=await f(`${s}.md`,"utf-8");else throw new Error(`Standard '${t}' not found at ${s}`)}return{id:t,content:e}}async resolveRegistry(){const t=h(this.projectRoot,"core","data","step-registry.json"),s=await f(t,"utf-8");return JSON.parse(s)}async assemblePrompt(t,s){const e=await this.resolveStep(t,s),c={"{story_id}":s.storyId,"{story_title}":s.storyTitle,"{step_id}":t,"{step_name}":e.frontmatter.name||t,"{current_status}":s.currentStatus,"{epic_id}":s.epicId,"{branch_name}":s.branchName,"{platform_target}":s.platformTarget};let o=e.content;for(const[r,i]of Object.entries(c))o=o.replaceAll(r,i);const n=[],a=e.frontmatter.skills;if(a&&typeof a=="string"){const r=a.split(",").map(i=>i.trim());for(const i of r)try{const l=await this.resolveSkill(i,s);o+=`
-
----
-
-# Skill: ${i}
-
-${l.content}`,n.push(i)}catch{}}return{prompt:o,variables:c,includedSkills:n,includedStandards:[]}}async isAvailable(){try{const t=h(this.projectRoot,"core");return await d(t),!0}catch{return!1}}async dispose(){}}export{P as LocalResolver};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * @neocortex/client - LocalResolver
+ *
+ * Resolves pipeline assets from the local filesystem.
+ * Used in development mode when core/ directory is available locally.
+ * Replicates the current CLI behavior of reading .md files directly.
+ */
+import { readFile, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { ResolverMode, } from '../types/index.js';
+// ── Frontmatter Parser ───────────────────────────────────────────────────
+const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---/;
+/**
+ * Parse YAML-like frontmatter from markdown content.
+ * Simple key-value parser sufficient for step/skill frontmatter.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(FRONTMATTER_REGEX);
+    if (!match) {
+        return { frontmatter: {}, body: content };
+    }
+    const frontmatter = {};
+    const lines = match[1].split('\n');
+    for (const line of lines) {
+        const colonIndex = line.indexOf(':');
+        if (colonIndex === -1)
+            continue;
+        const key = line.slice(0, colonIndex).trim().replace(/^['"]|['"]$/g, '');
+        let value = line.slice(colonIndex + 1).trim();
+        // Remove surrounding quotes
+        if (typeof value === 'string') {
+            value = value.replace(/^['"]|['"]$/g, '');
+        }
+        // Parse booleans
+        if (value === 'true')
+            value = true;
+        else if (value === 'false')
+            value = false;
+        frontmatter[key] = value;
+    }
+    const body = content.slice(match[0].length).trimStart();
+    return { frontmatter, body };
+}
+// ── LocalResolver Implementation ─────────────────────────────────────────
+export class LocalResolver {
+    mode = ResolverMode.LOCAL;
+    projectRoot;
+    stepPathIndex;
+    constructor(options) {
+        this.projectRoot = resolve(options.projectRoot);
+    }
+    async resolveStep(stepId, _context) {
+        const relativePath = (await this.resolveStepPathIndex()).get(stepId);
+        if (!relativePath)
+            throw new Error(`Step '${stepId}' is not present in the canonical registry`);
+        const fullPath = join(this.projectRoot, relativePath);
+        const raw = await readFile(fullPath, 'utf-8');
+        const { frontmatter, body } = parseFrontmatter(raw);
+        return {
+            id: stepId,
+            content: body,
+            frontmatter,
+        };
+    }
+    resolveStepPathIndex() {
+        this.stepPathIndex ??= this.loadStepPathIndex();
+        return this.stepPathIndex;
+    }
+    async loadStepPathIndex() {
+        const registryPath = join(this.projectRoot, 'core', 'data', 'step-registry.json');
+        const parsed = JSON.parse(await readFile(registryPath, 'utf8'));
+        const index = new Map();
+        const bootstrap = parsed['asset_bootstrap'];
+        if (bootstrap && typeof bootstrap === 'object' && !Array.isArray(bootstrap)) {
+            const assets = bootstrap['assets'];
+            if (!Array.isArray(assets))
+                throw new Error('manifest-generation-mismatch');
+            for (const raw of assets) {
+                if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                    throw new Error('manifest-schema-invalid');
+                const asset = raw;
+                if (asset['type'] !== 'step')
+                    continue;
+                const assetPath = asset['relative_path'];
+                if (typeof assetPath !== 'string' || !assetPath.startsWith('steps/') || assetPath.includes('..')) {
+                    throw new Error('manifest-schema-invalid');
+                }
+                const relativePath = `core/${assetPath}`;
+                const { frontmatter } = parseFrontmatter(await readFile(join(this.projectRoot, relativePath), 'utf8'));
+                const id = frontmatter['id'];
+                if (typeof id !== 'string' || !/^step-[a-z0-9][a-z0-9._-]*$/.test(id)) {
+                    throw new Error('manifest-required-step-unresolved');
+                }
+                if (index.has(id))
+                    throw new Error('manifest-duplicate-reference');
+                index.set(id, relativePath);
+            }
+        }
+        else {
+            // Explicit legacy partial projection: exact registry files only, with no
+            // category/path inference after a miss.
+            const groups = parsed['steps'];
+            if (!groups || typeof groups !== 'object' || Array.isArray(groups))
+                throw new Error('manifest-generation-mismatch');
+            for (const entries of Object.values(groups)) {
+                if (!Array.isArray(entries))
+                    continue;
+                for (const raw of entries) {
+                    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+                        throw new Error('manifest-schema-invalid');
+                    const entry = raw;
+                    const id = entry['id'];
+                    const file = entry['file'];
+                    if (typeof id !== 'string' || typeof file !== 'string' || !file.startsWith('core/steps/') || file.includes('..')) {
+                        throw new Error('manifest-schema-invalid');
+                    }
+                    if (index.has(id))
+                        throw new Error('manifest-duplicate-reference');
+                    index.set(id, file);
+                }
+            }
+        }
+        if (index.size === 0)
+            throw new Error('manifest-generation-mismatch');
+        return index;
+    }
+    async resolveSkill(skillId, _context) {
+        // Skills are organized in: core/skills/{category}/{skillId}.md
+        // or: core/skills/step-skills/{step}/{skillId}.md
+        // Try multiple paths to find the skill
+        const searchPaths = [
+            `core/skills/${skillId}.md`,
+            `core/skills/step-skills/${skillId}.md`,
+        ];
+        // Also try with nested path: "diagnose/prompt-enricher" -> core/skills/step-skills/diagnose/prompt-enricher.md
+        if (skillId.includes('/')) {
+            searchPaths.unshift(`core/skills/step-skills/${skillId}.md`);
+            searchPaths.unshift(`core/skills/${skillId}.md`);
+        }
+        let raw = null;
+        let resolvedPath = '';
+        for (const searchPath of searchPaths) {
+            const fullPath = join(this.projectRoot, searchPath);
+            try {
+                raw = await readFile(fullPath, 'utf-8');
+                resolvedPath = searchPath;
+                break;
+            }
+            catch {
+                // Try next path
+            }
+        }
+        if (raw === null) {
+            throw new Error(`Skill '${skillId}' not found. Searched: ${searchPaths.join(', ')}`);
+        }
+        const { frontmatter, body } = parseFrontmatter(raw);
+        return {
+            id: skillId,
+            content: body,
+            metadata: { ...frontmatter, resolvedPath },
+        };
+    }
+    async resolveStandard(standardId) {
+        const fullPath = join(this.projectRoot, 'core', 'standards', standardId);
+        let content;
+        try {
+            content = await readFile(fullPath, 'utf-8');
+        }
+        catch {
+            // Try with .md extension if not present
+            if (!standardId.endsWith('.md')) {
+                content = await readFile(`${fullPath}.md`, 'utf-8');
+            }
+            else {
+                throw new Error(`Standard '${standardId}' not found at ${fullPath}`);
+            }
+        }
+        return {
+            id: standardId,
+            content,
+        };
+    }
+    async resolveRegistry() {
+        const fullPath = join(this.projectRoot, 'core', 'data', 'step-registry.json');
+        const raw = await readFile(fullPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    async assemblePrompt(stepId, context) {
+        // Resolve the step content
+        const step = await this.resolveStep(stepId, context);
+        // Build variables map from context
+        const variables = {
+            '{story_id}': context.storyId,
+            '{story_title}': context.storyTitle,
+            '{step_id}': stepId,
+            '{step_name}': step.frontmatter['name'] || stepId,
+            '{current_status}': context.currentStatus,
+            '{epic_id}': context.epicId,
+            '{branch_name}': context.branchName,
+            '{platform_target}': context.platformTarget,
+        };
+        // Substitute variables in step content
+        let prompt = step.content;
+        for (const [key, value] of Object.entries(variables)) {
+            prompt = prompt.replaceAll(key, value);
+        }
+        // Resolve skills referenced in step frontmatter
+        const includedSkills = [];
+        const skillsRef = step.frontmatter['skills'];
+        if (skillsRef && typeof skillsRef === 'string') {
+            const skillIds = skillsRef.split(',').map((s) => s.trim());
+            for (const sid of skillIds) {
+                try {
+                    const skill = await this.resolveSkill(sid, context);
+                    prompt += `\n\n---\n\n# Skill: ${sid}\n\n${skill.content}`;
+                    includedSkills.push(sid);
+                }
+                catch {
+                    // Skill not found - skip
+                }
+            }
+        }
+        return {
+            prompt,
+            variables,
+            includedSkills,
+            includedStandards: [],
+        };
+    }
+    async isAvailable() {
+        try {
+            const corePath = join(this.projectRoot, 'core');
+            await access(corePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async dispose() {
+        // LocalResolver holds no resources to release
+    }
+}

package/packages/client/dist/resolvers/remote-resolver.js

@@ -1 +1,233 @@
-import{ResolverMode as u,NoOpCache as d}from"../types/index.js";import{CLIENT_VERSION as m}from"../version.js";const y=3e4,f=3,p=1e3,C=1e4;class i extends Error{statusCode;endpoint;constructor(t,e,r){super(t),this.statusCode=e,this.endpoint=r,this.name="RemoteResolverError"}}class v{mode=u.REMOTE;serverUrl;licenseKey;timeout;retryCount;cache;licenseClient;constructor(t){this.serverUrl=t.serverUrl.replace(/\/+$/,""),this.licenseKey=t.licenseKey,this.timeout=t.timeout??y,this.retryCount=t.retryCount??f,this.cache=t.cacheProvider??new d,this.licenseClient=t.licenseClient??null}async resolveStep(t,e){return this.fetchWithRetry({method:"GET",path:`/api/v1/steps/${encodeURIComponent(t)}`})}async resolveSkill(t,e){return this.fetchWithRetry({method:"GET",path:`/api/v1/skills/${encodeURIComponent(t)}`})}async resolveStandard(t){return this.fetchWithRetry({method:"GET",path:`/api/v1/standards/${encodeURIComponent(t)}`})}async resolveRegistry(){return this.fetchWithCacheFallback("registry",{method:"GET",path:"/api/v1/registry"})}async assemblePrompt(t,e){return this.fetchWithRetry({method:"POST",path:"/api/v1/prompts/assemble",body:{stepId:t,context:e}})}async isAvailable(){try{const t=new AbortController,e=setTimeout(()=>t.abort(),5e3),r=await fetch(`${this.serverUrl}/api/v1/health`,{method:"GET",headers:await this.buildHeaders(),signal:t.signal});return clearTimeout(e),r.ok}catch{return!1}}async dispose(){await this.cache.clear()}async buildHeaders(){const t={"Content-Type":"application/json","X-Client-Version":m};if(this.licenseClient){const e=await this.licenseClient.getToken();e&&(t.Authorization=`Bearer ${e}`)}return t}async fetchWithRetry(t){let e,r=!1;for(let a=0;a<=this.retryCount;a++)try{const o=new AbortController,n=setTimeout(()=>o.abort(),this.timeout),c=`${this.serverUrl}${t.path}`,h={method:t.method,headers:await this.buildHeaders(),signal:o.signal};t.body&&(h.body=JSON.stringify(t.body));const s=await fetch(c,h);if(clearTimeout(n),!s.ok){if(s.status===401&&!r&&this.licenseClient){if(r=!0,await this.licenseClient.forceRefresh()){a--;continue}throw new i(`API error: ${s.status}`,s.status)}throw s.status>=400&&s.status<500&&s.status!==429?new i(`API error: ${s.status}`,s.status):new i(`Server error: ${s.status}`,s.status)}return await s.json()}catch(o){if(e=o instanceof i?o:new i("Request failed"),o instanceof i&&o.statusCode&&o.statusCode>=400&&o.statusCode<500&&o.statusCode!==429)throw o;if(a<this.retryCount){const n=Math.min(p*Math.pow(2,a),C),c=Math.random()*n*.25;await this.sleep(n+c)}}throw e??new i("All retry attempts failed")}async fetchWithCacheFallback(t,e){try{const r=await this.fetchWithRetry(e);return this.cache.set(t,JSON.stringify(r)).catch(()=>{}),r}catch(r){const a=await this.cache.get(t);if(a!==null)try{return JSON.parse(a)}catch{}throw r}}sleep(t){return new Promise(e=>setTimeout(e,t))}}export{v as RemoteResolver,i as RemoteResolverError};
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+import { ResolverMode, NoOpCache, } from '../types/index.js';
+import { CLIENT_VERSION } from '../version.js';
+// ── Constants ────────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RETRY_COUNT = 3;
+const BACKOFF_BASE_MS = 1_000;
+const BACKOFF_MAX_MS = 10_000;
+// ── Error Types ──────────────────────────────────────────────────────────
+export class RemoteResolverError extends Error {
+    statusCode;
+    endpoint;
+    constructor(message, statusCode, endpoint) {
+        super(message);
+        this.statusCode = statusCode;
+        this.endpoint = endpoint;
+        this.name = 'RemoteResolverError';
+    }
+}
+// ── RemoteResolver Implementation ───────────────────────────────────────
+export class RemoteResolver {
+    mode = ResolverMode.REMOTE;
+    serverUrl;
+    licenseKey;
+    timeout;
+    retryCount;
+    /**
+     * Persistent cache -- used for registry metadata only, never protected
+     * step/skill/standard content.
+     */
+    cache;
+    licenseClient;
+    constructor(options) {
+        this.serverUrl = options.serverUrl.replace(/\/+$/, '');
+        this.licenseKey = options.licenseKey;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.retryCount = options.retryCount ?? DEFAULT_RETRY_COUNT;
+        this.cache = options.cacheProvider ?? new NoOpCache();
+        this.licenseClient = options.licenseClient ?? null;
+    }
+    async resolveStep(stepId, _context) {
+        return this.fetchWithRetry({
+            method: 'GET',
+            path: `/api/v1/steps/${encodeURIComponent(stepId)}`,
+        });
+    }
+    async resolveSkill(skillId, _context) {
+        return this.fetchWithRetry({
+            method: 'GET',
+            path: `/api/v1/skills/${encodeURIComponent(skillId)}`,
+        });
+    }
+    async resolveStandard(standardId) {
+        return this.fetchWithRetry({
+            method: 'GET',
+            path: `/api/v1/standards/${encodeURIComponent(standardId)}`,
+        });
+    }
+    async resolveRegistry() {
+        // Registry is NOT asset content -- it's tokenized metadata (P70.02).
+        // Persistent cache is acceptable here.
+        const cacheKey = 'registry';
+        return this.fetchWithCacheFallback(cacheKey, {
+            method: 'GET',
+            path: '/api/v1/registry',
+        });
+    }
+    async assemblePrompt(stepId, context) {
+        // assemblePrompt is not cached because it depends on dynamic context
+        return this.fetchWithRetry({
+            method: 'POST',
+            path: '/api/v1/prompts/assemble',
+            body: {
+                stepId,
+                context,
+            },
+        });
+    }
+    async isAvailable() {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5_000);
+            const response = await fetch(`${this.serverUrl}/api/v1/health`, {
+                method: 'GET',
+                headers: await this.buildHeaders(),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async dispose() {
+        await this.cache.clear();
+    }
+    // ── Private Methods ─────────────────────────────────────────────────
+    /**
+     * Build authorization headers for API requests.
+     * When a LicenseClient is available, uses JWT token from it.
+     * Story 31.04: NEVER sends raw license key as Bearer token.
+     * If JWT is unavailable, omits Authorization header entirely.
+     * Server will return 401, which fetchWithRetry handles via forceRefresh.
+     */
+    async buildHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Client-Version': CLIENT_VERSION,
+        };
+        if (this.licenseClient) {
+            const jwt = await this.licenseClient.getToken();
+            if (jwt) {
+                headers['Authorization'] = `Bearer ${jwt}`;
+            }
+            // No JWT available: omit Authorization header entirely
+            // Server will return 401, which fetchWithRetry handles via forceRefresh
+        }
+        return headers;
+    }
+    /**
+     * Execute HTTP request with retry and exponential backoff.
+     * Handles 401 specially: if a licenseClient is available, attempts
+     * forceRefresh() and retries once with the new token.
+     */
+    async fetchWithRetry(options) {
+        let lastError;
+        let authRetried = false;
+        for (let attempt = 0; attempt <= this.retryCount; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const url = `${this.serverUrl}${options.path}`;
+                const fetchOptions = {
+                    method: options.method,
+                    headers: await this.buildHeaders(),
+                    signal: controller.signal,
+                };
+                if (options.body) {
+                    fetchOptions.body = JSON.stringify(options.body);
+                }
+                const response = await fetch(url, fetchOptions);
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    // 401: attempt token refresh once if licenseClient is available
+                    if (response.status === 401 && !authRetried && this.licenseClient) {
+                        authRetried = true;
+                        const newToken = await this.licenseClient.forceRefresh();
+                        if (newToken) {
+                            // Retry immediately with the new token (don't count as a normal retry)
+                            attempt--; // offset the loop increment so this doesn't consume a retry
+                            continue;
+                        }
+                        // forceRefresh failed - throw immediately
+                        throw new RemoteResolverError(`API error: ${response.status}`, response.status);
+                    }
+                    // Don't retry on 4xx client errors (except 429 rate limit)
+                    if (response.status >= 400 && response.status < 500 && response.status !== 429) {
+                        throw new RemoteResolverError(`API error: ${response.status}`, response.status);
+                    }
+                    // Retry on 5xx server errors and 429 rate limit
+                    throw new RemoteResolverError(`Server error: ${response.status}`, response.status);
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                // Transport and parser exceptions can contain a URL, response fragment
+                // or adapter-specific diagnostics. They are not safe CLI output.
+                lastError = error instanceof RemoteResolverError
+                    ? error : new RemoteResolverError('Request failed');
+                // Don't retry on non-retryable errors (4xx except 429)
+                if (error instanceof RemoteResolverError && error.statusCode && error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429) {
+                    throw error;
+                }
+                // Apply backoff before next retry (except on last attempt)
+                if (attempt < this.retryCount) {
+                    const backoff = Math.min(BACKOFF_BASE_MS * Math.pow(2, attempt), BACKOFF_MAX_MS);
+                    // Add jitter (0-25% of backoff)
+                    const jitter = Math.random() * backoff * 0.25;
+                    await this.sleep(backoff + jitter);
+                }
+            }
+        }
+        throw lastError ?? new RemoteResolverError('All retry attempts failed');
+    }
+    /**
+     * Fetch with persistent cache fallback: try HTTP first, fall back to cache
+     * on failure. On successful HTTP response, update the cache.
+     *
+     * P70.06: ONLY the registry uses this path. Asset content (step/skill/
+     * standard) is fetched live and never touches disk or a fallback cache.
+     */
+    async fetchWithCacheFallback(cacheKey, options) {
+        try {
+            const result = await this.fetchWithRetry(options);
+            // Update cache with fresh data (fire-and-forget)
+            this.cache.set(cacheKey, JSON.stringify(result)).catch(() => {
+                // Cache write failures are non-critical
+            });
+            return result;
+        }
+        catch (error) {
+            // Try cache fallback
+            const cached = await this.cache.get(cacheKey);
+            if (cached !== null) {
+                try {
+                    return JSON.parse(cached);
+                }
+                catch {
+                    // Invalid cache data, rethrow original error
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Sleep for the specified duration.
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}